diff options
Diffstat (limited to 'doc/crypto')
271 files changed, 0 insertions, 29846 deletions
diff --git a/doc/crypto/ASN1_INTEGER_get_int64.pod b/doc/crypto/ASN1_INTEGER_get_int64.pod deleted file mode 100644 index 6fa1428c42..0000000000 --- a/doc/crypto/ASN1_INTEGER_get_int64.pod +++ /dev/null @@ -1,132 +0,0 @@ -=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/doc/crypto/ASN1_ITEM_lookup.pod b/doc/crypto/ASN1_ITEM_lookup.pod deleted file mode 100644 index 9ba69c9d34..0000000000 --- a/doc/crypto/ASN1_ITEM_lookup.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures - -=head1 SYNOPSIS - - #include <openssl/asn1.h> - - const ASN1_ITEM *ASN1_ITEM_lookup(const char *name); - const ASN1_ITEM *ASN1_ITEM_get(size_t i); - -=head1 DESCRIPTION - -ASN1_ITEM_lookup() returns the B<ASN1_ITEM name>. - -ASN1_ITEM_get() returns the B<ASN1_ITEM> with index B<i>. This function -returns B<NULL> if the index B<i> is out of range. - -=head1 RETURN VALUES - -ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid B<ASN1_ITEM> structure -or B<NULL> if an error occurred. - -=head1 SEE ALSO - -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/doc/crypto/ASN1_OBJECT_new.pod b/doc/crypto/ASN1_OBJECT_new.pod deleted file mode 100644 index 4c018efffd..0000000000 --- a/doc/crypto/ASN1_OBJECT_new.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions - -=head1 SYNOPSIS - - #include <openssl/asn1.h> - - ASN1_OBJECT *ASN1_OBJECT_new(void); - void ASN1_OBJECT_free(ASN1_OBJECT *a); - -=head1 DESCRIPTION - -The ASN1_OBJECT allocation routines, allocate and free an -ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER. - -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 - -Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it -is almost never used in applications. The ASN1 object utility functions -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)>. -Otherwise it returns a pointer to the newly allocated structure. - -ASN1_OBJECT_free() returns no value. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(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/doc/crypto/ASN1_STRING_length.pod b/doc/crypto/ASN1_STRING_length.pod deleted file mode 100644 index 26cb176142..0000000000 --- a/doc/crypto/ASN1_STRING_length.pod +++ /dev/null @@ -1,93 +0,0 @@ -=pod - -=head1 NAME - -ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, -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); - - int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b); - - int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); - - int ASN1_STRING_type(const ASN1_STRING *x); - - int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in); - -=head1 DESCRIPTION - -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_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 -are identical. The string types and content are compared. - -ASN1_STRING_set() sets the data of string B<str> to the buffer -B<data> or length B<len>. The supplied data is copied. If B<len> -is -1 then the length is determined by strlen(data). - -ASN1_STRING_type() returns the type of B<x>, using standard constants -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 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 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 -B<Time>. - -These functions should B<not> be used to examine or modify B<ASN1_INTEGER> -or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED> -utility functions should be used instead. - -In general it cannot be assumed that the data returned by ASN1_STRING_data() -is null terminated or does not contain embedded nulls. The actual format -of the data will depend on the actual string type itself: for example -for and IA5String the data will be ASCII, for a BMPString two bytes per -character in big endian format, UTF8String 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 SEE ALSO - -L<ERR_get_error(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/doc/crypto/ASN1_STRING_new.pod b/doc/crypto/ASN1_STRING_new.pod deleted file mode 100644 index 7bd2fc1921..0000000000 --- a/doc/crypto/ASN1_STRING_new.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free - -ASN1_STRING allocation functions - -=head1 SYNOPSIS - - #include <openssl/asn1.h> - - ASN1_STRING * ASN1_STRING_new(void); - ASN1_STRING * ASN1_STRING_type_new(int type); - void ASN1_STRING_free(ASN1_STRING *a); - -=head1 DESCRIPTION - -ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type -is undefined. - -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 - -Other string types call the B<ASN1_STRING> functions. For example -ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING). - -=head1 RETURN VALUES - -ASN1_STRING_new() and ASN1_STRING_type_new() return a valid -ASN1_STRING structure or B<NULL> if an error occurred. - -ASN1_STRING_free() does not return a value. - -=head1 SEE ALSO - -L<ERR_get_error(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/doc/crypto/ASN1_STRING_print_ex.pod b/doc/crypto/ASN1_STRING_print_ex.pod deleted file mode 100644 index d2bf538f6b..0000000000 --- a/doc/crypto/ASN1_STRING_print_ex.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -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, 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); - - -=head1 DESCRIPTION - -These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to -represent all the ASN1 string types. - -ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by -the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs -to B<fp> instead. - -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 '.'. - -=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 -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. - -Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters -determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control -characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the -MSB set are escaped: this option should B<not> be used if the terminal correctly -interprets UTF8 sequences. - -Escaping takes several forms. - -If the character being escaped is a 16 bit character then the form "\UXXXX" is used -using exactly four characters for the hex representation. If it is 32 bits then -"\WXXXXXXXX" is used using eight characters of its hex representation. These forms -will only be used if UTF8 conversion is not set (see below). - -Printable characters are normally escaped using the backslash '\' character. If -B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by -double quote characters: this is arguably more readable than the backslash -notation. Other characters use the "\XX" using exactly two characters of the hex -representation. - -If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8 -format first. If the terminal supports the display of UTF8 sequences then this -option will correctly display multi byte characters. - -If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at -all: everything is assumed to be one byte per character. This is primarily for -debugging purposes and can result in confusing output in multi character strings. - -If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out -before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str(). - -The content of a string instead of being interpreted can be "dumped": this just -outputs the value of the string using the form #XXXX using hex format for each -octet. - -If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped. - -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 -B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped -instead (including tag and length octets). - -B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is -equivalent to: - ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | - ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER - -=head1 SEE ALSO - -L<X509_NAME_print_ex(3)>, -L<ASN1_tag2str(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/doc/crypto/ASN1_TIME_set.pod b/doc/crypto/ASN1_TIME_set.pod deleted file mode 100644 index 457b7218d4..0000000000 --- a/doc/crypto/ASN1_TIME_set.pod +++ /dev/null @@ -1,138 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t); - ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, - int offset_day, long offset_sec); - int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); - int ASN1_TIME_check(const ASN1_TIME *t); - int ASN1_TIME_print(BIO *b, const ASN1_TIME *s); - - int ASN1_TIME_diff(int *pday, int *psec, - const ASN1_TIME *from, const ASN1_TIME *to); - -=head1 DESCRIPTION - -The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the -time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME -structure is allocated and returned. - -ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented -by the time B<offset_day> and B<offset_sec> after the time_t value B<t>. -The values of B<offset_day> or B<offset_sec> can be negative to set a -time before B<t>. The B<offset_sec> value can also exceed the number of -seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated -and returned. - -ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time -represented by string B<str> which must be in appropriate ASN.1 time -format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). - -ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>. - -ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable -format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example -"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time -structure has invalid format it prints out "Bad time value" and returns -an error. - -ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between -B<from> and B<to>. If B<to> represents a time later than B<from> then -one or both (depending on the time difference) of B<*pday> and B<*psec> -will be positive. If B<to> represents a time earlier than B<from> then -one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from> -represent the same time then B<*pday> and B<*psec> will both be zero. -If both B<*pday> and B<*psec> are non-zero they will always have the same -sign. The value of B<*psec> will always be less than the number of seconds -in a day. If B<from> or B<to> is NULL the current time is used. - -=head1 NOTES - -The ASN1_TIME structure corresponds to the ASN.1 structure B<Time> -defined in RFC5280 et al. The time setting functions obey the rules outlined -in RFC5280: if the date can be represented by UTCTime it is used, else -GeneralizedTime is used. - -The ASN1_TIME structure is represented as an ASN1_STRING internally and can -be freed up using ASN1_STRING_free(). - -The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt -is made to correct ancient calendar changes (for example from Julian to -Gregorian calendars). - -Some applications add offset times directly to a time_t value and pass the -results to ASN1_TIME_set() (or equivalent). This can cause problems as the -time_t value can overflow on some systems resulting in unexpected results. -New applications should use ASN1_TIME_adj() instead and pass the offset value -in the B<offset_sec> and B<offset_day> parameters instead of directly -manipulating a time_t value. - -=head1 BUGS - -ASN1_TIME_print() currently does not print out the time zone: it either prints -out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT -anyway. - -=head1 EXAMPLES - -Set a time structure to one hour after the current time and print it out: - - #include <time.h> - #include <openssl/asn1.h> - ASN1_TIME *tm; - time_t t; - BIO *b; - t = time(NULL); - tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); - b = BIO_new_fp(stdout, BIO_NOCLOSE); - ASN1_TIME_print(b, tm); - ASN1_STRING_free(tm); - BIO_free(b); - -Determine if one time is later or sooner than the current time: - - int day, sec; - - if (!ASN1_TIME_diff(&day, &sec, NULL, to)) - /* Invalid time format */ - - if (day > 0 || sec > 0) - printf("Later\n"); - else if (day < 0 || sec < 0) - printf("Sooner\n"); - else - printf("Same\n"); - -=head1 RETURN VALUES - -ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure -or NULL if an error occurred. - -ASN1_TIME_set_string() returns 1 if the time value is successfully set and -0 otherwise. - -ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0 -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 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/doc/crypto/ASN1_TYPE_get.pod b/doc/crypto/ASN1_TYPE_get.pod deleted file mode 100644 index 70c56878b8..0000000000 --- a/doc/crypto/ASN1_TYPE_get.pod +++ /dev/null @@ -1,100 +0,0 @@ -=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/doc/crypto/ASN1_generate_nconf.pod b/doc/crypto/ASN1_generate_nconf.pod deleted file mode 100644 index 92f624fa24..0000000000 --- a/doc/crypto/ASN1_generate_nconf.pod +++ /dev/null @@ -1,270 +0,0 @@ -=pod - -=head1 NAME - -ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions - -=head1 SYNOPSIS - - #include <openssl/asn1.h> - - ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf); - ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf); - -=head1 DESCRIPTION - -These functions generate the ASN1 encoding of a string -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 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. - -=head1 GENERATION STRING FORMAT - -The actual data encoded is determined by the string B<str> and -the configuration information. The general format of the string -is: - -=over 2 - -=item B<[modifier,]type[:value]> - -=back - -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 - -The supported types are listed below. Unless otherwise specified -only the B<ASCII> format is permissible. - -=over 2 - -=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. - -=item B<NULL> - -Encode the B<NULL> type, the B<value> string must not be present. - -=item B<INTEGER>, B<INT> - -Encodes an ASN1 B<INTEGER> type. The B<value> string represents -the value of the integer, it can be prefaced by a minus sign and -is normally interpreted as a decimal value unless the prefix B<0x> -is included. - -=item B<ENUMERATED>, B<ENUM> - -Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to -B<INTEGER>. - -=item B<OBJECT>, B<OID> - -Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be -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>. - -=item B<GENERALIZEDTIME>, B<GENTIME> - -Encodes an ASN1 B<GeneralizedTime> structure, the value should be in -the format B<YYYYMMDDHHMMSSZ>. - -=item B<OCTETSTRING>, B<OCT> - -Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents -of this structure, the format strings B<ASCII> and B<HEX> can be -used to specify the format of B<value>. - -=item B<BITSTRING>, B<BITSTR> - -Encodes an ASN1 B<BIT STRING>. B<value> represents the contents -of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST> -can be used to specify the format of B<value>. - -If the format is anything other than B<BITLIST> the number of unused -bits is set to zero. - -=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>, -B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>, -B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>, -B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>, -B<NUMERIC> - -These encode the corresponding string types. B<value> represents the -contents of this structure. The format can be B<ASCII> or B<UTF8>. - -=item B<SEQUENCE>, B<SEQ>, B<SET> - -Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value> -should be a section name which will contain the contents. The -field names in the section are ignored and the values are in the -generated string format. If B<value> is absent then an empty SEQUENCE -will be encoded. - -=back - -=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 - -=item B<EXPLICIT>, B<EXP> - -Add an explicit tag to the following structure. This string -should be followed by a colon and the tag value to use as a -decimal value. - -By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL, -APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used, -the default is CONTEXT SPECIFIC. - -=item B<IMPLICIT>, B<IMP> - -This is the same as B<EXPLICIT> except IMPLICIT tagging is used -instead. - -=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP> - -The following structure is surrounded by an OCTET STRING, a SEQUENCE, -a SET or a BIT STRING respectively. For a BIT STRING the number of unused -bits is set to zero. - -=item B<FORMAT> - -This specifies the format of the ultimate value. It should be followed -by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>. - -If no format specifier is included then B<ASCII> is used. If B<UTF8> is -specified then the value string must be a valid B<UTF8> string. For B<HEX> the -output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT -STRING) is a comma separated list of the indices of the set bits, all other -bits are zero. - -=back - -=head1 EXAMPLES - -A simple IA5String: - - IA5STRING:Hello World - -An IA5String explicitly tagged: - - EXPLICIT:0,IA5STRING:Hello World - -An IA5String explicitly tagged using APPLICATION tagging: - - EXPLICIT:0A,IA5STRING:Hello World - -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 consisting of a BOOL an OID and a UTF8String: - - asn1 = SEQUENCE:seq_section - - [seq_section] - - field1 = BOOLEAN:TRUE - field2 = OID:commonName - field3 = UTF8:Third field - -This example produces an RSAPrivateKey structure, this is the -key contained in the file client.pem in all OpenSSL distributions -(note: the field names such as 'coeff' are ignored and are present just -for clarity): - - asn1=SEQUENCE:private_key - [private_key] - version=INTEGER:0 - - n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ - D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 - - e=INTEGER:0x010001 - - d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\ - F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D - - p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\ - D4BD57 - - q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\ - 46EC4F - - exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\ - 9C0A39B9 - - exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\ - E7B2458F - - coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\ - 628657053A - -This example is the corresponding public key in a SubjectPublicKeyInfo -structure: - - # Start with a SEQUENCE - asn1=SEQUENCE:pubkeyinfo - - # pubkeyinfo contains an algorithm identifier and the public key wrapped - # in a BIT STRING - [pubkeyinfo] - algorithm=SEQUENCE:rsa_alg - pubkey=BITWRAP,SEQUENCE:rsapubkey - - # algorithm ID for RSA is just an OID and a NULL - [rsa_alg] - algorithm=OID:rsaEncryption - parameter=NULL - - # Actual public key: modulus and exponent - [rsapubkey] - n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ - D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 - - e=INTEGER:0x010001 - -=head1 RETURN VALUES - -ASN1_generate_nconf() and ASN1_generate_v3() return the encoded -data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred. - -The error codes that can be obtained by L<ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)> - -=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/doc/crypto/ASYNC_WAIT_CTX_new.pod b/doc/crypto/ASYNC_WAIT_CTX_new.pod deleted file mode 100644 index 580c4e5dd7..0000000000 --- a/doc/crypto/ASYNC_WAIT_CTX_new.pod +++ /dev/null @@ -1,144 +0,0 @@ -=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_fds_have_changed() 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/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod deleted file mode 100644 index c10a66f565..0000000000 --- a/doc/crypto/ASYNC_start_job.pod +++ /dev/null @@ -1,330 +0,0 @@ -=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/doc/crypto/BF_encrypt.pod b/doc/crypto/BF_encrypt.pod deleted file mode 100644 index 0401e90a20..0000000000 --- a/doc/crypto/BF_encrypt.pod +++ /dev/null @@ -1,117 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/blowfish.h> - - void BF_set_key(BF_KEY *key, int len, const unsigned char *data); - - 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); - void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, - 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); - 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); - -=head1 DESCRIPTION - -This library implements the Blowfish cipher, which was invented and described -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)>). Blowfish is currently one -of the faster block ciphers. It is quite a bit faster than DES, and much -faster than IDEA or RC2. - -Blowfish consists of a key setup phase and the actual encryption or decryption -phase. - -BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key -at B<data>. - -BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. -It encrypts or decrypts the first 64 bits of B<in> using the key B<key>, -putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>) -or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by -B<in> and B<out> must be 64 bits in length, no less. If they are larger, -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 -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 -B<ivec> is simply initialized to zero. -BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while -BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable -number of bytes (the amount does not have to be an exact multiple of 8). The -purpose of the latter two is to simulate stream ciphers, and therefore, they -need the parameter B<num>, which is a pointer to an integer where the current -offset in B<ivec> is stored between calls. This integer must be initialized -to zero when B<ivec> is initialized. - -BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It -encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>, -putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or -decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte -long initialization vector. - -BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. -It encrypts or decrypts the bytes in B<in> using the key B<schedule>, -putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>) -or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an -8 byte long initialization vector. B<num> must point at an integer which must -be initially zero. - -BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. -It uses the same parameters as BF_cfb64_encrypt(), which must be initialized -the same way. - -BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish -encryption. They encrypt/decrypt the first 64 bits of the vector pointed by -B<data>, using the key B<key>. These functions should not be used unless you -implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt(). -If you still want to use these functions, you should be aware that they take -each 32-bit chunk in host-byte order, which is little-endian on little-endian -platforms and big-endian on big-endian ones. - -=head1 RETURN VALUES - -None of the functions presented here return any value. - -=head1 NOTE - -Applications should use the higher level functions -L<EVP_EncryptInit(3)> etc. instead of calling these -functions directly. - -=head1 SEE ALSO - -L<EVP_EncryptInit(3)>, -L<des_modes(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/doc/crypto/BIO_ADDR.pod b/doc/crypto/BIO_ADDR.pod deleted file mode 100644 index 4b169e8a89..0000000000 --- a/doc/crypto/BIO_ADDR.pod +++ /dev/null @@ -1,125 +0,0 @@ -=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/doc/crypto/BIO_ADDRINFO.pod b/doc/crypto/BIO_ADDRINFO.pod deleted file mode 100644 index 9ebf99a814..0000000000 --- a/doc/crypto/BIO_ADDRINFO.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=head1 NAME - -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/doc/crypto/BIO_connect.pod b/doc/crypto/BIO_connect.pod deleted file mode 100644 index 5194033feb..0000000000 --- a/doc/crypto/BIO_connect.pod +++ /dev/null @@ -1,112 +0,0 @@ -=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/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod deleted file mode 100644 index 17dc6ed903..0000000000 --- a/doc/crypto/BIO_ctrl.pod +++ /dev/null @@ -1,135 +0,0 @@ -=pod - -=head1 NAME - -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 - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); - - 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_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); - -=head1 DESCRIPTION - -BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() -are BIO "control" operations taking arguments of various types. -These functions are not normally called directly, various macros -are used instead. The standard macros are described below, macros -specific to a particular type of BIO are described in the specific -BIOs manual page as well as any special features of the standard -calls. - -BIO_reset() typically resets a BIO to some initial state, in the case -of file related BIOs for example it rewinds the file pointer to the -start of the file. - -BIO_seek() resets a file related BIO's (that is file descriptor and -FILE BIOs) file position pointer to B<ofs> bytes from start of file. - -BIO_tell() returns the current file position of a file related BIO. - -BIO_flush() normally writes out any internally buffered data, in some -cases it is used to signal EOF and that no more data will be written. - -BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of -"EOF" varies according to the BIO type. - -BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can -take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used -in a source/sink BIO to indicate that the underlying I/O stream should -be closed when the BIO is freed. - -BIO_get_close() returns the BIOs close flag. - -BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() -return the number of pending characters in the BIOs read and write buffers. -Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() -return a size_t type and are functions, BIO_pending() and BIO_wpending() are -macros which call BIO_ctrl(). - -=head1 RETURN VALUES - -BIO_reset() normally returns 1 for success and 0 or -1 for failure. File -BIOs are an exception, they return 0 for success and -1 for failure. - -BIO_seek() and BIO_tell() both return the current file position on success -and -1 for failure, except file BIOs which for BIO_seek() always return 0 -for success and -1 for failure. - -BIO_flush() returns 1 for success and 0 or -1 for failure. - -BIO_eof() returns 1 if EOF has been reached 0 otherwise. - -BIO_set_close() always returns 1. - -BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. - -BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() -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(). -The BIO_should_retry() call should be used and appropriate action taken -is the call fails. - -The return values of BIO_pending() and BIO_wpending() may not reliably -determine the amount of pending data in all cases. For example in the -case of a file BIO some data may be available in the FILE structures -internal buffers but it is not possible to determine this in a -portably way. For other types of BIO they may not be supported. - -Filter BIOs if they do not internally handle a particular BIO_ctrl() -operation usually pass the operation to the next BIO in the chain. -This often means there is no need to locate the required BIO for -a particular operation, it can be called on a chain and it will -be automatically passed to the relevant BIO. However this can cause -unexpected results: for example no current filter BIOs implement -BIO_seek(), but this may still succeed if the chain ends in a FILE -or file descriptor BIO. - -Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() -operation. - -=head1 BUGS - -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. - -=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/doc/crypto/BIO_f_base64.pod b/doc/crypto/BIO_f_base64.pod deleted file mode 100644 index 19df1dd638..0000000000 --- a/doc/crypto/BIO_f_base64.pod +++ /dev/null @@ -1,91 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_base64 - base64 BIO filter - -=for comment multiple includes - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/evp.h> - - const BIO_METHOD *BIO_f_base64(void); - -=head1 DESCRIPTION - -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(). - -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 -to flush the final block through the BIO. - -The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags() -to encode the data all on one line or expect the data to be all -on one line. - -=head1 NOTES - -Because of the format of base64 encoding the end of the encoded -block cannot always be reliably determined. - -=head1 RETURN VALUES - -BIO_f_base64() returns the base64 BIO method. - -=head1 EXAMPLES - -Base64 encode the string "Hello World\n" and write the result -to standard output: - - BIO *bio, *b64; - char message[] = "Hello World \n"; - - b64 = BIO_new(BIO_f_base64()); - bio = BIO_new_fp(stdout, BIO_NOCLOSE); - BIO_push(b64, bio); - BIO_write(b64, message, strlen(message)); - BIO_flush(b64); - - BIO_free_all(b64); - -Read Base64 encoded data from standard input and write the decoded -data to standard output: - - BIO *bio, *b64, *bio_out; - char inbuf[512]; - int inlen; - - b64 = BIO_new(BIO_f_base64()); - 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); - - BIO_flush(bio_out); - BIO_free_all(b64); - -=head1 BUGS - -The ambiguity of EOF in base64 encoded data can cause additional -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 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/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod deleted file mode 100644 index 3224710942..0000000000 --- a/doc/crypto/BIO_f_buffer.pod +++ /dev/null @@ -1,92 +0,0 @@ -=pod - -=head1 NAME - -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> - - const BIO_METHOD *BIO_f_buffer(void); - - 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 - -BIO_f_buffer() returns the buffering BIO method. - -Data written to a buffering BIO is buffered and periodically written -to the next BIO in the chain. Data read from a buffering BIO comes from -an internal buffer which is filled from the next BIO in the chain. -Both BIO_gets() and BIO_puts() are supported. - -Calling BIO_reset() on a buffering BIO clears any buffered data. - -BIO_get_buffer_num_lines() returns the number of lines currently buffered. - -BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() -set the read, write or both read and write buffer sizes to B<size>. The initial -buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the -buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared -when the buffer is resized. - -BIO_set_buffer_read_data() clears the read buffer and fills it with B<num> -bytes of B<buf>. If B<num> is larger than the current buffer size the buffer -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 -support it (for example SSL BIOs). - -Data is only written to the next BIO in the chain when the write buffer fills -or when BIO_flush() is called. It is therefore important to call BIO_flush() -whenever any pending data should be written such as when removing a buffering -BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate -source/sink BIO is non blocking. - -=head1 RETURN VALUES - -BIO_f_buffer() returns the buffering BIO method. - -BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0). - -BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() -return 1 if the buffer was successfully resized or 0 for failure. - -BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if -there was an error. - -=head1 SEE ALSO - -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/doc/crypto/BIO_f_cipher.pod b/doc/crypto/BIO_f_cipher.pod deleted file mode 100644 index 87ab3ccc9d..0000000000 --- a/doc/crypto/BIO_f_cipher.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -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> - - 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) - -=head1 DESCRIPTION - -BIO_f_cipher() returns the cipher BIO method. This is a filter -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(). - -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 -to flush and possibly pad the final block through the BIO. - -BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key> -and IV B<iv>. B<enc> should be set to 1 for encryption and zero for -decryption. - -When reading from an encryption BIO the final block is automatically -decrypted and checked when EOF is detected. BIO_get_cipher_status() -is a BIO_ctrl() macro which can be called to determine whether the -decryption operation was successful. - -BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal -BIO cipher context. The retrieved context can be used in conjunction -with the standard cipher routines to set it up. This is useful when -BIO_set_cipher() is not flexible enough for the applications needs. - -=head1 NOTES - -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 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. - -As always, if BIO_gets() or BIO_puts() support is needed then it can -be achieved by preceding the cipher BIO with a buffering BIO. - -=head1 RETURN VALUES - -BIO_f_cipher() returns the cipher BIO method. - -BIO_set_cipher() does not return a value. - -BIO_get_cipher_status() returns 1 for a successful decrypt and 0 -for failure. - -BIO_get_cipher_ctx() currently always returns 1. - -=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/doc/crypto/BIO_f_md.pod b/doc/crypto/BIO_f_md.pod deleted file mode 100644 index 32f0046751..0000000000 --- a/doc/crypto/BIO_f_md.pod +++ /dev/null @@ -1,156 +0,0 @@ -=pod - -=head1 NAME - -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> - - 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 - -BIO_f_md() returns the message digest BIO method. This is a filter -BIO that digests any data passed through it, it is a BIO wrapper -for the digest routines EVP_DigestInit(), EVP_DigestUpdate() -and EVP_DigestFinal(). - -Any data written or read through a digest BIO using BIO_read() and -BIO_write() is digested. - -BIO_gets(), if its B<size> parameter is large enough finishes the -digest calculation and returns the digest value. BIO_puts() is -not supported. - -BIO_reset() reinitialises a digest BIO. - -BIO_set_md() sets the message digest of BIO B<b> to B<md>: this -must be called to initialize a digest BIO before any data is -passed through it. It is a BIO_ctrl() macro. - -BIO_get_md() places the a pointer to the digest BIOs digest method -in B<mdp>, it is a BIO_ctrl() macro. - -BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>. - -=head1 NOTES - -The context returned by BIO_get_md_ctx() can be used in calls -to EVP_DigestFinal() and also the signature routines EVP_SignFinal() -and EVP_VerifyFinal(). - -The context returned by BIO_get_md_ctx() is an internal context -structure. Changes made to this context will affect the digest -BIO itself and the context pointer will become invalid when the digest -BIO is freed. - -After the digest has been retrieved from a digest BIO it must be -reinitialized by calling BIO_reset(), or BIO_set_md() before any more -data is passed through it. - -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. - -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 - -BIO_f_md() returns the digest BIO method. - -BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and -0 for failure. - -=head1 EXAMPLES - -The following example creates a BIO chain containing an SHA1 and MD5 -digest BIO and passes the string "Hello World" through it. Error -checking has been omitted for clarity. - - BIO *bio, *mdtmp; - char message[] = "Hello World"; - bio = BIO_new(BIO_s_null()); - mdtmp = BIO_new(BIO_f_md()); - BIO_set_md(mdtmp, EVP_sha1()); - /* For BIO_push() we want to append the sink BIO and keep a note of - * the start of the chain. - */ - bio = BIO_push(mdtmp, bio); - mdtmp = BIO_new(BIO_f_md()); - BIO_set_md(mdtmp, EVP_md5()); - bio = BIO_push(mdtmp, bio); - /* Note: mdtmp can now be discarded */ - BIO_write(bio, message, strlen(message)); - -The next example digests data by reading through a chain instead: - - BIO *bio, *mdtmp; - char buf[1024]; - int rdlen; - bio = BIO_new_file(file, "rb"); - mdtmp = BIO_new(BIO_f_md()); - BIO_set_md(mdtmp, EVP_sha1()); - bio = BIO_push(mdtmp, bio); - mdtmp = BIO_new(BIO_f_md()); - BIO_set_md(mdtmp, EVP_md5()); - bio = BIO_push(mdtmp, bio); - do { - rdlen = BIO_read(bio, buf, sizeof(buf)); - /* Might want to do something with the data here */ - } 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. - - BIO *mdtmp; - unsigned char mdbuf[EVP_MAX_MD_SIZE]; - int mdlen; - int i; - 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); - 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); - - BIO_free_all(bio); - -=head1 BUGS - -The lack of support for BIO_puts() and the non standard behaviour of -BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() -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 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>. - -=cut diff --git a/doc/crypto/BIO_f_null.pod b/doc/crypto/BIO_f_null.pod deleted file mode 100644 index c4e4c667c1..0000000000 --- a/doc/crypto/BIO_f_null.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_null - null filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - const BIO_METHOD * BIO_f_null(void); - -=head1 DESCRIPTION - -BIO_f_null() returns the null filter BIO method. This is a filter BIO -that does nothing. - -All requests to a null filter BIO are passed through to the next BIO in -the chain: this means that a BIO chain containing a null filter BIO -behaves just as though the BIO was not there. - -=head1 NOTES - -As may be apparent a null filter BIO is not particularly useful. - -=head1 RETURN VALUES - -BIO_f_null() returns the null filter BIO method. - -=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/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod deleted file mode 100644 index 3f9635ee68..0000000000 --- a/doc/crypto/BIO_f_ssl.pod +++ /dev/null @@ -1,298 +0,0 @@ -=pod - -=head1 NAME - -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> - - const BIO_METHOD *BIO_f_ssl(void); - - 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_connect(SSL_CTX *ctx); - BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); - int BIO_ssl_copy_session_id(BIO *to, BIO *from); - void BIO_ssl_shutdown(BIO *bio); - - 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. - -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 -then an attempt is made to establish one on the first I/O call. - -If a BIO is appended to an SSL BIO using BIO_push() it is automatically -used as the SSL BIOs read and write BIOs. - -Calling BIO_reset() on an SSL BIO closes down any current SSL connection -by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in -the chain: this will typically disconnect the underlying transport. -The SSL BIO is then reset to the initial accept or connect state. - -If the close flag is set when an SSL BIO is freed then the internal -SSL structure is also freed using SSL_free(). - -BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using -the close flag B<c>. - -BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be -manipulated using the standard SSL library functions. - -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) -the SSL session is automatically renegotiated. B<num> must be at -least 512 bytes. - -BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to -B<seconds>. When the renegotiate timeout elapses the session is -automatically renegotiated. - -BIO_get_num_renegotiates() returns the total number of session -renegotiations due to I/O or timeout. - -BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using -client mode if B<client> is non zero. - -BIO_new_ssl_connect() creates a new BIO chain consisting of an -SSL BIO (using B<ctx>) followed by a connect BIO. - -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 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. - -BIO_ssl_shutdown() closes down an SSL connection on BIO -chain B<bio>. It does this by locating the SSL BIO in the -chain and calling SSL_shutdown() on its internal SSL -pointer. - -BIO_do_handshake() attempts to complete an SSL handshake on the -supplied BIO and establish the SSL connection. It returns 1 -if the connection was established successfully. A zero or negative -value is returned if the connection could not be established, the -call BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. If an SSL connection has -already been established this call has no effect. - -=head1 NOTES - -SSL BIOs are exceptional in that if the underlying transport -is non blocking they can still request a retry in exceptional -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. - -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. - -Since unknown BIO_ctrl() operations are sent through filter -BIOs the servers name and port can be set using BIO_set_host() -on the BIO returned by BIO_new_ssl_connect() without having -to locate the connect BIO first. - -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. - -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 *sbio, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - /* XXX Seed the PRNG if needed. */ - - ctx = SSL_CTX_new(TLS_client_method()); - - /* XXX Set verify paths and mode here. */ - - sbio = BIO_new_ssl_connect(ctx); - BIO_get_ssl(sbio, &ssl); - 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); - - /* XXX We might want to do other things with ssl here */ - - /* 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); - exit(1); - } - if (BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error establishing SSL connection\n"); - ERR_print_errors_fp(stderr); - exit(1); - } - - /* 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); - } - BIO_free_all(sbio); - BIO_free(out); - -Here is a simple server example. It makes use of a buffering -BIO to allow lines to be read from the SSL BIO using BIO_gets. -It creates a pseudo web page containing the actual request from -a client and also echoes the request to standard output. - - BIO *sbio, *bbio, *acpt, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - /* XXX Seed the PRNG if needed. */ - - 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); - } - - /* XXX Other things like set verify locations, EDH temp callbacks. */ - - /* New SSL BIO setup as server */ - sbio = BIO_new_ssl(ctx, 0); - BIO_get_ssl(sbio, &ssl); - if (ssl == NULL) { - fprintf(stderr, "Can't locate SSL pointer\n"); - ERR_print_errors_fp(stderr); - exit(1); - } - - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - bbio = BIO_new(BIO_f_buffer()); - sbio = BIO_push(bbio, sbio); - acpt = BIO_new_accept("4433"); - - /* - * 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. - */ - 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); - exit(1); - } - - 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 */ - 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); - 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; - } - - BIO_puts(sbio, "--------------------------------------------------\r\n"); - BIO_puts(sbio, "\r\n"); - BIO_flush(sbio); - BIO_free_all(sbio); - -=head1 BUGS - -In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, -the I/O BIO reference count was incorrectly incremented (instead of -decremented) and dissociated with the SSL BIO even if the SSL BIO was not -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 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/doc/crypto/BIO_find_type.pod b/doc/crypto/BIO_find_type.pod deleted file mode 100644 index ff7b488609..0000000000 --- a/doc/crypto/BIO_find_type.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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 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. - -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 -certain type. - -BIO_method_type() returns the type of a BIO. - -=head1 RETURN VALUES - -BIO_find_type() returns a matching BIO or NULL for no match. - -BIO_next() returns the next BIO in a chain. - -BIO_method_type() returns the type of the BIO B<b>. - -=head1 EXAMPLE - -Traverse a chain looking for digest BIOs: - - BIO *btmp; - 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_next(btmp); - } while (btmp); - - -=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/doc/crypto/BIO_get_data.pod b/doc/crypto/BIO_get_data.pod deleted file mode 100644 index 14f21fa720..0000000000 --- a/doc/crypto/BIO_get_data.pod +++ /dev/null @@ -1,65 +0,0 @@ -=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 version 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/doc/crypto/BIO_get_ex_new_index.pod b/doc/crypto/BIO_get_ex_new_index.pod deleted file mode 100644 index 3e24f10bc3..0000000000 --- a/doc/crypto/BIO_get_ex_new_index.pod +++ /dev/null @@ -1,64 +0,0 @@ -=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, -ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_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/doc/crypto/BIO_meth_new.pod b/doc/crypto/BIO_meth_new.pod deleted file mode 100644 index bf3316104d..0000000000 --- a/doc/crypto/BIO_meth_new.pod +++ /dev/null @@ -1,131 +0,0 @@ -=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 version 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/doc/crypto/BIO_new.pod b/doc/crypto/BIO_new.pod deleted file mode 100644 index 006cf5925c..0000000000 --- a/doc/crypto/BIO_new.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -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(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_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. -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_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 - -If BIO_free() is called on a BIO chain it will only free one BIO resulting -in a memory leak. - -Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() -on it other than the discarded return value. - -=head1 HISTORY - -BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque. - -=head1 EXAMPLE - -Create a memory BIO: - - BIO *mem = BIO_new(BIO_s_mem()); - -=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/doc/crypto/BIO_new_CMS.pod b/doc/crypto/BIO_new_CMS.pod deleted file mode 100644 index b06c224f71..0000000000 --- a/doc/crypto/BIO_new_CMS.pod +++ /dev/null @@ -1,75 +0,0 @@ -=pod - -=head1 NAME - -BIO_new_CMS - CMS streaming filter BIO - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms); - -=head1 DESCRIPTION - -BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output -of the filter is written to B<out>. Any data written to the chain is -automatically translated to a BER format CMS structure of the appropriate type. - -=head1 NOTES - -The chain returned by this function behaves like a standard filter BIO. It -supports non blocking I/O. Content is processed and streamed on the fly and not -all held in memory at once: so it is possible to encode very large structures. -After all content has been written through the chain BIO_flush() must be called -to finalise the structure. - -The B<CMS_STREAM> flag must be included in the corresponding B<flags> -parameter of the B<cms> creation function. - -If an application wishes to write additional data to B<out> BIOs should be -removed from the chain using BIO_pop() and freed with BIO_free() until B<out> -is reached. If no additional data needs to be written BIO_free_all() can be -called to free up the whole chain. - -Any content written through the filter is used verbatim: no canonical -translation is performed. - -It is possible to chain multiple BIOs to, for example, create a triple wrapped -signed, enveloped, signed structure. In this case it is the applications -responsibility to set the inner content type of any outer CMS_ContentInfo -structures. - -Large numbers of small writes through the chain should be avoided as this will -produce an output consisting of lots of OCTET STRING structures. Prepending -a BIO_f_buffer() buffering BIO will prevent this. - -=head1 BUGS - -There is currently no corresponding inverse BIO: i.e. one which can decode -a CMS structure on the fly. - -=head1 RETURN VALUES - -BIO_new_CMS() returns a BIO chain when successful or NULL if an error -occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -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/doc/crypto/BIO_parse_hostserv.pod b/doc/crypto/BIO_parse_hostserv.pod deleted file mode 100644 index 4ee4f46a84..0000000000 --- a/doc/crypto/BIO_parse_hostserv.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -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/doc/crypto/BIO_push.pod b/doc/crypto/BIO_push.pod deleted file mode 100644 index 762027ff6a..0000000000 --- a/doc/crypto/BIO_push.pod +++ /dev/null @@ -1,89 +0,0 @@ -=pod - -=head1 NAME - -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); - void BIO_set_next(BIO *b, BIO *next); - -=head1 DESCRIPTION - -The BIO_push() function appends the BIO B<append> to B<b>, it returns -B<b>. - -BIO_pop() removes the BIO B<b> from a chain and returns the next BIO -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() -joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, -the deleted BIO does not need to be at the end of a chain. - -The process of calling BIO_push() and BIO_pop() on a BIO may have additional -consequences (a control call is made to the affected BIOs) any effects will -be noted in the descriptions of individual BIOs. - -=head1 EXAMPLES - -For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is -a base64 BIO and B<f> is a file BIO. - -If the call: - - BIO_push(b64, f); - -is made then the new chain will be B<b64-f>. After making the calls - - BIO_push(md2, b64); - BIO_push(md1, md2); - -the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested -by B<md1> and B<md2>, B<base64> encoded and written to B<f>. - -It should be noted that reading causes data to pass in the reverse -direction, that is data is read from B<f>, base64 B<decoded> and digested -by B<md1> and B<md2>. If the call: - - BIO_pop(md2); - -The call will return B<b64> and the new chain will be B<md1-b64-f> data can -be written to B<md1> as before. - -=head1 RETURN VALUES - -BIO_push() returns the end of the chain, B<b>. - -BIO_pop() returns the next BIO in the chain, or NULL if there is no next -BIO. - -=head1 SEE ALSO - -L<bio> - -=head1 HISTORY - -The BIO_set_next() function was added in OpenSSL version 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/doc/crypto/BIO_read.pod b/doc/crypto/BIO_read.pod deleted file mode 100644 index 45871c1be9..0000000000 --- a/doc/crypto/BIO_read.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions - -=head1 SYNOPSIS - - #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); - -=head1 DESCRIPTION - -BIO_read() attempts to read B<len> bytes from BIO B<b> and places -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-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 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 trailing -NUL is not included in the length returned by BIO_gets(). - -=head1 NOTES - -A 0 or -1 return is not necessarily an indication of an error. In -particular when the source/sink is non-blocking or of a certain type -it may merely be an indication that no data is currently available and that -the application should retry the operation later. - -One technique sometimes used with blocking sockets is to use a system call -(such as select(), poll() or equivalent) to determine when data is available -and then call read() to read the data. The equivalent with BIOs (that is call -select() on the underlying I/O structure and then call BIO_read() to -read the data) should B<not> be used because a single call to BIO_read() -can cause several reads (and writes in the case of SSL BIOs) on the underlying -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)> 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)> -to the chain. - -=head1 SEE ALSO - -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/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod deleted file mode 100644 index ce9995dc3f..0000000000 --- a/doc/crypto/BIO_s_accept.pod +++ /dev/null @@ -1,222 +0,0 @@ -=pod - -=head1 NAME - -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> - - const BIO_METHOD *BIO_s_accept(void); - - 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); - - long BIO_set_nbio_accept(BIO *b, int n); - 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); - - int BIO_do_accept(BIO *b); - -=head1 DESCRIPTION - -BIO_s_accept() returns the accept BIO method. This is a wrapper -round the platform's TCP/IP socket accept routines. - -Using accept BIOs, TCP/IP connections can be accepted and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on an accept BIO will perform I/O -on the underlying connection. If no connection is established -and the port (see below) is set up properly then the BIO -waits for an incoming connection. - -Accept BIOs support BIO_puts() but not BIO_gets(). - -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 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_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 "*" 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>. - -BIO_set_nbio_accept() sets the accept socket to blocking mode -(the default) if B<n> is 0 or non blocking mode if B<n> is 1. - -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 -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 B<BIO_BIND_NORMAL> (the default) is set -then another socket cannot be bound to the same port. If -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 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 -to create the accept socket and bind an address to it. Second -and subsequent calls to BIO_do_accept() will await an incoming -connection, or request a retry in non blocking mode. - -=head1 NOTES - -When an accept BIO is at the end of a chain it will await an -incoming connection before processing I/O calls. When an accept -BIO is not at then end of a chain it passes I/O calls to the next -BIO in the chain. - -When a connection is established a new socket BIO is created for -the connection and appended to the chain. That is the chain is now -accept->socket. This effectively means that attempting I/O on -an initial accept socket will await an incoming connection then -perform I/O on it. - -If any additional BIOs have been set using BIO_set_accept_bios() -then they are placed between the socket and the accept BIO, -that is the chain will be accept->otherbios->socket. - -If a server wishes to process multiple connections (as is normally -the case) then the accept BIO must be made available for further -incoming connections. This can be done by waiting for a connection and -then calling: - - connection = BIO_pop(accept); - -After this call B<connection> will contain a BIO for the recently -established connection and B<accept> will now be a single BIO -again which can be used to await further incoming connections. -If no further connections will be accepted the B<accept> can -be freed using BIO_free(). - -If only a single connection will be processed it is possible to -perform I/O using the accept BIO itself. This is often undesirable -however because the accept BIO will still accept additional incoming -connections. This can be resolved by using BIO_pop() (see above) -and freeing up the accept BIO after the initial connection. - -If the underlying accept socket is non-blocking and BIO_do_accept() is -called to await an incoming connection it is possible for -BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens -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_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 - -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 - -This example accepts two connections on port 4444, sends messages -down each and finally closes both down. - - BIO *abio, *cbio, *cbio2; - - /* First call to BIO_accept() sets up accept BIO */ - 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(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(1); - } - fprintf(stderr, "Connection 2 established\n"); - - /* Close accept BIO to refuse further connections */ - cbio2 = BIO_pop(abio); - BIO_free(abio); - BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); - 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 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/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod deleted file mode 100644 index cb46546e21..0000000000 --- a/doc/crypto/BIO_s_bio.pod +++ /dev/null @@ -1,201 +0,0 @@ -=pod - -=head1 NAME - -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 - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - const BIO_METHOD *BIO_s_bio(void); - - int BIO_make_bio_pair(BIO *b1, BIO *b2); - int BIO_destroy_bio_pair(BIO *b); - int BIO_shutdown_wr(BIO *b); - - - 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); - - int BIO_get_write_guarantee(BIO *b); - size_t BIO_ctrl_get_write_guarantee(BIO *b); - 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 - -BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink -BIOs where data written to either half of the pair is buffered and can be read from -the other half. Both halves must usually by handled by the same application thread -since no locking is done on the internal data structures. - -Since BIO chains typically end in a source/sink BIO it is possible to make this -one half of a BIO pair and have all the data processed by the chain under application -control. - -One typical use of BIO pairs is to place TLS/SSL I/O under application control, this -can be used when the application wishes to use a non standard transport for -TLS/SSL or the normal socket routines are inappropriate. - -Calls to BIO_read() will read data from the buffer or request a retry if no -data is available. - -Calls to BIO_write() will place data in the buffer or request a retry if the -buffer is full. - -The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to -determine the amount of pending data in the read or write buffer. - -BIO_reset() clears any data in the write buffer. - -BIO_make_bio_pair() joins two separate BIOs into a connected pair. - -BIO_destroy_pair() destroys the association between two connected BIOs. Freeing -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. - -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 -17K, sufficient for a maximum size TLS record. - -BIO_get_write_buf_size() returns the size of the write buffer. - -BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and -BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> -with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is -zero then the default size is used. BIO_new_bio_pair() does not check whether -B<bio1> or B<bio2> do point to some other BIO, the values are overwritten, -BIO_free() is not called. - -BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum -length of data that can be currently written to the BIO. Writes larger than this -value will return a value from BIO_write() less than the amount requested or if the -buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function -whereas BIO_get_write_guarantee() is a macro. - -BIO_get_read_request() and BIO_ctrl_get_read_request() return the -amount of data requested, or the buffer size if it is less, if the -last read attempt at the other half of the BIO pair failed due to an -empty buffer. This can be used to determine how much data should be -written to the BIO so the next read will succeed: this is most useful -in TLS/SSL applications where the amount of data read is usually -meaningful rather than just a buffer size. After a successful read -this call will return zero. It also will return zero once new data -has been written satisfying the read request or part of it. -Note that BIO_get_read_request() never returns an amount larger -than that returned by BIO_get_write_guarantee(). - -BIO_ctrl_reset_read_request() can also be used to reset the value returned by -BIO_get_read_request() to zero. - -=head1 NOTES - -Both halves of a BIO pair should be freed. That is even if one half is implicit -freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. - -When used in bidirectional applications (such as TLS/SSL) care should be taken to -flush any data in the write buffer. This can be done by calling BIO_pending() -on the other half of the pair and, if any data is pending, reading it and sending -it to the underlying transport. This must be done before any normal processing -(such as calling select() ) due to a request and BIO_should_read() being true. - -To see why this is important consider a case where a request is sent using -BIO_write() and a response read with BIO_read(), this can occur during an -TLS/SSL handshake for example. BIO_write() will succeed and place data in the write -buffer. BIO_read() will initially fail and BIO_should_read() will be true. If -the application then waits for data to be available on the underlying transport -before flushing the write buffer it will never succeed because the request was -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 -B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the -locations for B<bio1> and B<bio2>. Check the error stack for more information. - -[XXXXX: More return values need to be added here] - -=head1 EXAMPLE - -The BIO pair can be used to have full control over the network access of an -application. The application can call select() on the socket as required -without having to go through the SSL-interface. - - BIO *internal_bio, *network_bio; - ... - BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); - SSL_set_bio(ssl, internal_bio, internal_bio); - SSL_operations(); //e.g SSL_read and SSL_write - ... - - application | TLS-engine - | | - +----------> SSL_operations() - | /\ || - | || \/ - | BIO-pair (internal_bio) - | BIO-pair (network_bio) - | || /\ - | \/ || - +-----------< BIO_operations() - | | - | | - socket - - ... - SSL_free(ssl); /* implicitly frees internal_bio */ - BIO_free(network_bio); - ... - -As the BIO pair will only buffer the data and never directly access the -connection, it behaves non-blocking and will return as soon as the write -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 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 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 -the peer might be waiting for the data before being able to continue. - -=head1 SEE ALSO - -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/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod deleted file mode 100644 index 2143acd099..0000000000 --- a/doc/crypto/BIO_s_connect.pod +++ /dev/null @@ -1,200 +0,0 @@ -=pod - -=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_get_conn_hostname, -BIO_get_conn_port, -BIO_set_nbio, BIO_do_connect - connect BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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_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); - - int BIO_do_connect(BIO *b); - -=head1 DESCRIPTION - -BIO_s_connect() returns the connect BIO method. This is a wrapper -round the platform's TCP/IP socket connection routines. - -Using connect BIOs, TCP/IP connections can be made and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on a connect BIO will perform I/O -on the underlying connection. If no connection is established -and the port and hostname (see below) is set up properly then -a connection is established first. - -Connect BIOs support BIO_puts() but not BIO_gets(). - -If the close flag is set on a connect BIO then any active -connection is shutdown and the socket closed when the BIO -is freed. - -Calling BIO_reset() on a connect BIO will close any active -connection and reset the BIO into a state where it can connect -to the same host again. - -BIO_get_fd() places the underlying 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_set_conn_hostname() uses the string B<name> to set the hostname. -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. This internal -list is http, telnet, socks, https, ssl, ftp, and gopher. - -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_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 -non blocking I/O is set during the connect process. - -BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into -a single call: that is it creates a new connect BIO with B<name>. - -BIO_do_connect() attempts to connect the supplied BIO. It returns 1 -if the connection was established successfully. A zero or negative -value is returned if the connection could not be established, the -call BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. - -=head1 NOTES - -If blocking I/O is set then a non positive return value from any -I/O call is caused by an error condition, although a zero return -will normally mean that the connection was closed. - -If the port name is supplied as part of the host name then this will -override any value set with BIO_set_conn_port(). This may be undesirable -if the application does not wish to allow connection to arbitrary -ports. This can be avoided by checking for the presence of the ':' -character in the passed hostname and either indicating an error or -truncating the string at that point. - -The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), -BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a -connection attempt is made. Before any connection attempt the values -returned are those set by the application itself. - -Applications do not have to call BIO_do_connect() but may wish to do -so to separate the connection process from other I/O processing. - -If non blocking I/O is set then retries will be requested as appropriate. - -It addition to BIO_should_read() and BIO_should_write() it is also -possible for BIO_should_io_special() to be true during the initial -connection process with the reason BIO_RR_CONNECT. If this is returned -then this is an indication that a connection attempt would block, -the application should then take appropriate action to wait until -the underlying socket has connected and retry the call. - -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_set_nbio() and -BIO_do_connect() are macros. - -=head1 RETURN VALUES - -BIO_s_connect() returns the connect BIO method. - -BIO_get_fd() returns the socket or -1 if the BIO has not -been initialized. - -BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and -BIO_set_conn_int_port() always return 1. - -BIO_get_conn_hostname() returns the connected hostname or NULL is -none was set. - -BIO_get_conn_port() returns a string representing the connected -port or NULL if not set. - -BIO_get_conn_ip() returns a pointer to the connected IP address in -binary form or all zeros if not set. - -BIO_get_conn_int_port() returns the connected port or 0 if none was -set. - -BIO_set_nbio() always returns 1. - -BIO_do_connect() returns 1 if the connection was successfully -established and 0 or -1 if the connection failed. - -=head1 EXAMPLE - -This is example connects to a webserver on the local host and attempts -to retrieve a page and copy the result to standard output. - - - BIO *cbio, *out; - int len; - char tmpbuf[1024]; - - 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); - 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); - } - BIO_free(cbio); - BIO_free(out); - - -=head1 SEE ALSO - -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/doc/crypto/BIO_s_fd.pod b/doc/crypto/BIO_s_fd.pod deleted file mode 100644 index 79c4a5999f..0000000000 --- a/doc/crypto/BIO_s_fd.pod +++ /dev/null @@ -1,98 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - const BIO_METHOD *BIO_s_fd(void); - - 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); - -=head1 DESCRIPTION - -BIO_s_fd() returns the file descriptor BIO method. This is a wrapper -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 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 -such as by using B<lseek(fd, 0, 0)>. - -BIO_seek() sets the file pointer to position B<ofs> from start of file -such as by using B<lseek(fd, ofs, 0)>. - -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. - -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 -file descriptor is in a non blocking mode then the BIO will behave in the -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_set_fd() always returns 1. - -BIO_get_fd() returns the file descriptor or -1 if the BIO has not -been initialized. - -BIO_new_fd() returns the newly allocated BIO or NULL is an error -occurred. - -=head1 EXAMPLE - -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)>, 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/doc/crypto/BIO_s_file.pod b/doc/crypto/BIO_s_file.pod deleted file mode 100644 index e19d824290..0000000000 --- a/doc/crypto/BIO_s_file.pod +++ /dev/null @@ -1,159 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, -BIO_read_filename, BIO_write_filename, BIO_append_filename, -BIO_rw_filename - FILE bio - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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); - - int BIO_read_filename(BIO *b, char *name) - int BIO_write_filename(BIO *b, char *name) - int BIO_append_filename(BIO *b, char *name) - int BIO_rw_filename(BIO *b, char *name) - -=head1 DESCRIPTION - -BIO_s_file() returns the BIO file method. As its name implies it -is a wrapper round the stdio FILE structure and it is a -source/sink BIO. - -Calls to BIO_read() and BIO_write() read and write data to the -underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs. - -BIO_flush() on a file BIO calls the fflush() function on the wrapped -stream. - -BIO_reset() attempts to change the file pointer to the start of file -using fseek(stream, 0, 0). - -BIO_seek() sets the file pointer to position B<ofs> from start of file -using fseek(stream, ofs, 0). - -BIO_eof() calls feof(). - -Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO -is freed. - -BIO_new_file() creates a new file BIO with mode B<mode> the meaning -of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE -flag is set on the returned BIO. - -BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be: -BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying -stream to text mode, default is binary: this only has any effect under -Win32). - -BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same -meaning as in BIO_new_fp(), it is a macro. - -BIO_get_fp() retrieves the fp of a file BIO, it is a macro. - -BIO_seek() is a macro that sets the position pointer to B<offset> bytes -from the start of file. - -BIO_tell() returns the value of the position pointer. - -BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and -BIO_rw_filename() set the file BIO B<b> to use file B<name> for -reading, writing, append or read write respectively. - -=head1 NOTES - -When wrapping stdout, stdin or stderr the underlying stream should not -normally be closed so the BIO_NOCLOSE flag should be set. - -Because the file BIO calls the underlying stdio functions any quirks -in stdio behaviour will be mirrored by the corresponding BIO. - -On Windows BIO_new_files reserves for the filename argument to be -UTF-8 encoded. In other words if you have to make it work in multi- -lingual environment, encode file names in UTF-8. - -=head1 EXAMPLES - -File BIO "hello world": - - BIO *bio_out; - bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); - BIO_printf(bio_out, "Hello World\n"); - -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 ... */ - BIO_printf(bio_out, "Hello World\n"); - -Write to a file: - - BIO *out; - out = BIO_new_file("filename.txt", "w"); - if (!out) /* Error occurred */ - BIO_printf(out, "Hello World\n"); - BIO_free(out); - -Alternative technique: - - BIO *out; - out = BIO_new(BIO_s_file()); - if (out == NULL) /* Error ... */ - if (!BIO_write_filename(out, "filename.txt")) /* Error ... */ - BIO_printf(out, "Hello World\n"); - BIO_free(out); - -=head1 RETURN VALUES - -BIO_s_file() returns the file BIO method. - -BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error -occurred. - -BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure -(although the current implementation never return 0). - -BIO_seek() returns the same value as the underlying fseek() function: -0 for success or -1 for failure. - -BIO_tell() returns the current file position. - -BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and -BIO_rw_filename() return 1 for success or 0 for failure. - -=head1 BUGS - -BIO_reset() and BIO_seek() are implemented using fseek() on the underlying -stream. The return value for fseek() is 0 for success or -1 if an error -occurred this differs from other types of BIO which will typically return -1 for success and a non positive value if an error occurred. - -=head1 SEE ALSO - -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/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod deleted file mode 100644 index b272c410a0..0000000000 --- a/doc/crypto/BIO_s_mem.pod +++ /dev/null @@ -1,124 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - const BIO_METHOD * BIO_s_mem(void); - const BIO_METHOD * BIO_s_secmem(void); - - 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 *BIO_new_mem_buf(const void *buf, int len); - -=head1 DESCRIPTION - -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. - -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 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. - -BIO_ctrl_pending() returns the number of bytes currently stored. - -BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is -empty. If the B<v> is zero then an empty memory BIO will return EOF (that is -it will return zero and BIO_should_retry(b) will be false. If B<v> is non -zero then it will return B<v> when it is empty and it will set the read retry -flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal -positive return value B<v> should be set to a negative value, typically -1. - -BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data -and returns the total amount of data available. It is implemented as a macro. - -BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the -close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE. -It is a macro. - -BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is -a macro. - -BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>, -if B<len> is -1 then the B<buf> is assumed to be nul terminated and its -length is determined by B<strlen>. The BIO is set to a read only state and -as a result cannot be written to. This is useful when some data needs to be -made available from a static area of memory in the form of a BIO. The -supplied data is read directly from the supplied buffer: it is B<not> copied -first, so the supplied area of memory must be unchanged until the BIO is freed. - -=head1 NOTES - -Writes to memory BIOs will always succeed if memory is available: that is -their size can grow indefinitely. - -Every read from a read write memory BIO will remove the data just read with -an internal copy operation, if a BIO contains a lot of data and it is -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. - -=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"); - -Create a read only memory BIO: - - char data[] = "Hello World"; - BIO *mem; - mem = BIO_new_mem_buf(data, -1); - -Extract the BUF_MEM structure from a memory BIO and then free up the BIO: - - BUF_MEM *bptr; - BIO_get_mem_ptr(mem, &bptr); - BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ - BIO_free(mem); - -=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/doc/crypto/BIO_s_null.pod b/doc/crypto/BIO_s_null.pod deleted file mode 100644 index 5a1d84dd2c..0000000000 --- a/doc/crypto/BIO_s_null.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_null - null data sink - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - const BIO_METHOD * BIO_s_null(void); - -=head1 DESCRIPTION - -BIO_s_null() returns the null sink BIO method. Data written to -the null sink is discarded, reads return EOF. - -=head1 NOTES - -A null sink BIO behaves in a similar manner to the Unix /dev/null -device. - -A null bio can be placed on the end of a chain to discard any data -passed through it. - -A null sink is useful if, for example, an application wishes to digest some -data by writing through a digest bio but not send the digested data anywhere. -Since a BIO chain must normally include a source/sink BIO this can be achieved -by adding a null sink BIO to the end of the chain - -=head1 RETURN VALUES - -BIO_s_null() returns the null sink BIO method. - -=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/doc/crypto/BIO_s_socket.pod b/doc/crypto/BIO_s_socket.pod deleted file mode 100644 index ad0574aee6..0000000000 --- a/doc/crypto/BIO_s_socket.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_socket, BIO_new_socket - socket BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - const BIO_METHOD *BIO_s_socket(void); - - BIO *BIO_new_socket(int sock, int close_flag); - -=head1 DESCRIPTION - -BIO_s_socket() returns the socket BIO method. This is a wrapper -round the platform's socket routines. - -BIO_read() and BIO_write() read or write the underlying socket. -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_new_socket() returns a socket BIO using B<sock> and B<close_flag>. - -=head1 NOTES - -Socket BIOs also support any relevant functionality of file descriptor -BIOs. - -The reason for having separate file descriptor and socket BIOs is that on some -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. - -=head1 RETURN VALUES - -BIO_s_socket() returns the socket BIO method. - -BIO_new_socket() returns the newly allocated BIO or NULL is an error -occurred. - -=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/doc/crypto/BIO_set_callback.pod b/doc/crypto/BIO_set_callback.pod deleted file mode 100644 index 113b416488..0000000000 --- a/doc/crypto/BIO_set_callback.pod +++ /dev/null @@ -1,131 +0,0 @@ -=pod - -=head1 NAME - -BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, -BIO_debug_callback - BIO callback functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - - typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, - long argl, long ret); - - void BIO_set_callback(BIO *b, BIO_callack_fn cb); - BIO_callack_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_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 it is interpreted as a BIO to send the information -to, otherwise stderr is used. - -BIO_callback_fn() is the type of the callback function. The meaning of each -argument is described below: - -=over - -=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<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. - -=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 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. - -=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. - -=item B<BIO_read(b, out, outl)> - -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)> - -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)> - -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)> - -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. - -=back - -=head1 EXAMPLE - -The BIO_debug_callback() function is a good example, its source is -in crypto/bio/bio_cb.c - -=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/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod deleted file mode 100644 index d6ddf48e2c..0000000000 --- a/doc/crypto/BIO_should_retry.pod +++ /dev/null @@ -1,132 +0,0 @@ -=pod - -=head1 NAME - -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_set_retry_reason - BIO retry -functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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); - - 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 - -These functions determine why a BIO is not able to read or write data. -They will typically be called after a failed BIO_read() or BIO_write() -call. - -BIO_should_retry() is true if the call that produced this condition -should then be retried at a later time. - -If BIO_should_retry() is false then the cause is an error condition. - -BIO_should_read() is true if the cause of the condition is that a BIO -needs to read data. - -BIO_should_write() is true if the cause of the condition is that a BIO -needs to read data. - -BIO_should_io_special() is true if some "special" condition, that is a -reason other than reading or writing is the cause of the condition. - -BIO_retry_type() returns a mask of the cause of a retry condition -consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, -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 -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. - -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 -0 and BIO_should_retry() is false then the cause will be that the -connection closed. A similar condition on a file BIO will mean that it -has reached EOF. Some BIO types may place additional information on -the error queue. For more details see the individual BIO type manual -pages. - -If the underlying I/O structure is in a blocking mode almost all current -BIO types will not request a retry, because the underlying I/O -calls will not. If the application knows that the BIO type will never -signal a retry then it need not call BIO_should_retry() after a failed -BIO I/O call. This is typically done with file BIOs. - -SSL BIOs are the only current exception to this rule: they can request a -retry even if the underlying I/O structure is blocking, if a handshake -occurs during a call to BIO_read(). An application can retry the failed -call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY -on the underlying SSL structure. - -While an application may retry a failed non blocking call immediately -this is likely to be very inefficient because the call will fail -repeatedly until data can be processed or is available. An application -will normally wait until the necessary condition is satisfied. How -this is done depends on the underlying I/O structure. - -For example if the cause is ultimately a socket and BIO_should_read() -is true then a call to select() may be made to wait until data is -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. - -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 -the platforms I/O functions. This is often not desirable: one solution -is to use non blocking I/O and use a timeout on the select() (or -equivalent) call. - -=head1 BUGS - -The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: -that is they cannot retry after a partial read or write. This is usually -worked around by only passing the relevant data to ASN1 functions when -the entire structure can be read or written. - -=head1 SEE ALSO - -L<bio> - -=head1 HISTORY - -The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in -OpenSSL version 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/doc/crypto/BN_BLINDING_new.pod b/doc/crypto/BN_BLINDING_new.pod deleted file mode 100644 index 5f56aa3fc9..0000000000 --- a/doc/crypto/BN_BLINDING_new.pod +++ /dev/null @@ -1,126 +0,0 @@ -=pod - -=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_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); - 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); - 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); - -=head1 DESCRIPTION - -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 -necessary parameters are set, by re-creating the blinding parameters. - -BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>. -If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be -returned in B<r> (this is useful if a B<RSA> object is shared among -several threads). BN_BLINDING_invert_ex() multiplies B<n> with the -inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as -the inverse blinding. - -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_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 -B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the -automatic update of the B<BN_BLINDING> parameters after each use -and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation -of the B<BN_BLINDING> parameters after a fixed number of uses (currently -32). In newly allocated B<BN_BLINDING> objects no flags are set. -BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags. - -BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters -using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and -B<m_ctx> can be used to pass special functions for exponentiation -(normally BN_mod_exp_mont() and B<BN_MONT_CTX>). - -=head1 RETURN VALUES - -BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure -or NULL in case of an error. - -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_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> -parameters or NULL on error. - -=head1 SEE ALSO - -L<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(). - -=head1 COPYRIGHT - -Copyright 2005-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/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod deleted file mode 100644 index ca54590517..0000000000 --- a/doc/crypto/BN_CTX_new.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_CTX *BN_CTX_new(void); - - BN_CTX *BN_CTX_secure_new(void); - - void BN_CTX_free(BN_CTX *c); - -=head1 DESCRIPTION - -A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by -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_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)> 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(). -If B<c> is NULL, nothing is done. - -=head1 RETURN VALUES - -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. - -=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)>, L<ERR_get_error(3)>, L<BN_add(3)>, -L<BN_CTX_start(3)> - -=head1 HISTORY - -BN_CTX_init() was removed 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/doc/crypto/BN_CTX_start.pod b/doc/crypto/BN_CTX_start.pod deleted file mode 100644 index 372da506d9..0000000000 --- a/doc/crypto/BN_CTX_start.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - void BN_CTX_start(BN_CTX *ctx); - - BIGNUM *BN_CTX_get(BN_CTX *ctx); - - void BN_CTX_end(BN_CTX *ctx); - -=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)>) -in order to save the overhead of repeatedly creating and -freeing B<BIGNUM>s in functions that are called from inside a loop. - -A function must call BN_CTX_start() first. Then, BN_CTX_get() may be -called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get() -calls must be made before calling any other functions that use the -B<ctx> as an argument. - -Finally, BN_CTX_end() must be called before returning from the function. -When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from -BN_CTX_get() become invalid. - -=head1 RETURN VALUES - -BN_CTX_start() and BN_CTX_end() return no values. - -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)>. - - -=head1 SEE ALSO - -L<BN_CTX_new(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/doc/crypto/BN_add.pod b/doc/crypto/BN_add.pod deleted file mode 100644 index 72cc09f67a..0000000000 --- a/doc/crypto/BN_add.pod +++ /dev/null @@ -1,127 +0,0 @@ -=pod - -=head1 NAME - -BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add, -BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd - -arithmetic operations on BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - 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 *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - - int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - - int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - - int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - - int BN_mod_sqr(BIGNUM *r, 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); - -=head1 DESCRIPTION - -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_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>. -This function is faster than BN_mul(r,a,a). - -BN_div() divides I<a> by I<d> and places the result in I<dv> and the -remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may -be B<NULL>, in which case the respective value is not returned. -The result is rounded towards zero; thus if I<a> is negative, the -remainder will be zero or negative. -For division by powers of 2, use BN_rshift(3). - -BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>. - -BN_nnmod() reduces I<a> modulo I<m> and places the non-negative -remainder in I<r>. - -BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative -result in I<r>. - -BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the -non-negative result in I<r>. - -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)> 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>. - -BN_exp() raises I<a> to the I<p>-th power and places the result in I<r> -(C<r=a^p>). This function is faster than repeated applications of -BN_mul(). - -BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p % -m>). This function uses less time and space than BN_exp(). - -BN_gcd() computes the greatest common divisor of I<a> and I<b> and -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)>. - -Unless noted otherwise, the result B<BIGNUM> must be different from -the arguments. - -=head1 RETURN VALUES - -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)>. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(3)>, L<BN_CTX_new(3)>, -L<BN_add_word(3)>, L<BN_set_bit(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/doc/crypto/BN_add_word.pod b/doc/crypto/BN_add_word.pod deleted file mode 100644 index 35bdcf45c6..0000000000 --- a/doc/crypto/BN_add_word.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic -functions on BIGNUMs with integers - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - 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); - -=head1 DESCRIPTION - -These functions perform arithmetic operations on BIGNUMs with unsigned -integers. They are much more efficient than the normal BIGNUM -arithmetic operations. - -BN_add_word() adds B<w> to B<a> (C<a+=w>). - -BN_sub_word() subtracts B<w> from B<a> (C<a-=w>). - -BN_mul_word() multiplies B<a> and B<w> (C<a*=w>). - -BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder. - -BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%w>). - -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)>. - -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)>, L<ERR_get_error(3)>, L<BN_add(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/doc/crypto/BN_bn2bin.pod b/doc/crypto/BN_bn2bin.pod deleted file mode 100644 index b272010ba0..0000000000 --- a/doc/crypto/BN_bn2bin.pod +++ /dev/null @@ -1,116 +0,0 @@ -=pod - -=head1 NAME - -BN_bn2binpad, -BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec, -BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi, -BN_mpi2bn - format conversions - -=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); - 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); - -=head1 DESCRIPTION - -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() 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. - -BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>, -with a leading '-' for negative numbers, to the B<BIO> or B<FILE> -B<fp>. - -BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format -that consists of the number's length in bytes represented as a 4-byte -big-endian number, and the number itself in big-endian format, where -the most significant bit signals a negative number (the representation -of numbers with the MSB set is prefixed with null byte). - -BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to> -must be large enough to hold the result. The size can be determined by -calling BN_bn2mpi(B<a>, NULL). - -BN_mpi2bn() converts the B<len> bytes long representation at B<s> to -a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM> -if B<ret> is NULL. - -=head1 RETURN VALUES - -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 the length of valid -representation in hexadecimal or decimal digits, and 0 on error, in which -case no new B<BIGNUM> will be created. - -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)>. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(3)>, L<BN_zero(3)>, -L<ASN1_INTEGER_to_BN(3)>, -L<BN_num_bytes(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/doc/crypto/BN_cmp.pod b/doc/crypto/BN_cmp.pod deleted file mode 100644 index ec005718a1..0000000000 --- a/doc/crypto/BN_cmp.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - 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); - -=head1 DESCRIPTION - -BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their -absolute values. - -BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1, -or B<w> respectively. BN_is_odd() tests if a is odd. - -BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros. - -=head1 RETURN VALUES - -BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if -B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values -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 - -L<bn(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/doc/crypto/BN_copy.pod b/doc/crypto/BN_copy.pod deleted file mode 100644 index b044b98a0b..0000000000 --- a/doc/crypto/BN_copy.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BN_copy, BN_dup, BN_with_flags - copy BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from); - - 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 4 - -=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)>. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(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/doc/crypto/BN_generate_prime.pod b/doc/crypto/BN_generate_prime.pod deleted file mode 100644 index 0472b9b829..0000000000 --- a/doc/crypto/BN_generate_prime.pod +++ /dev/null @@ -1,194 +0,0 @@ -=pod - -=head1 NAME - -BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, -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, - 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_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); - - BN_GENCB *BN_GENCB_new(void); - - 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, - 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 -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 - -=item * - -B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th -potential prime number. - -=item * - -While the number is being tested for primality, -B<BN_GENCB_call(cb, 1, j)> is called as described below. - -=item * - -When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called. - -=back - -The prime may have to fulfill additional requirements for use in -Diffie-Hellman key exchange: - -If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add> -== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given -generator. - -If B<safe> is true, it will be a safe prime (i.e. a prime p so -that (p-1)/2 is also prime). - -The PRNG must be seeded prior to calling BN_generate_prime_ex(). -The prime number generation has a negligible error probability. - -BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is -prime. The following tests are performed until one of them shows that -B<p> is composite; if B<p> passes all these tests, it is considered -prime. - -BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>, -first attempts trial division by a number of small primes; -if no divisors are found by this test and B<cb> is not B<NULL>, -B<BN_GENCB_call(cb, 1, -1)> is called. -If B<do_trial_division == 0>, this test is skipped. - -Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin -probabilistic primality test with B<nchecks> iterations. If -B<nchecks == BN_prime_checks>, a number of iterations is used that -yields a false positive rate of at most 2^-80 for random input. - -If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called -after the j-th iteration (j = 0, 1, ...). B<ctx> is a -pre-allocated B<BN_CTX> (to save the overhead of allocating and -freeing the structure in a loop), or B<NULL>. - -BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure -and passes the ints B<a> and B<b> as arguments. There are two types of -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 -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 -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 -the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are -deprecated and can be compared to BN_is_prime_ex and -BN_is_prime_fasttest_ex respectively. - -=head1 RETURN VALUES - -BN_generate_prime_ex() return 1 on success or 0 on error. - -BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and -BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is -prime with an error probability of less than 0.25^B<nchecks>, and --1 on error. - -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)>. - -=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)>, L<ERR_get_error(3)>, L<rand(3)> - -=head1 HISTORY - -BN_GENCB_new(), BN_GENCB_free(), -and BN_GENCB_get_arg() 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/doc/crypto/BN_mod_inverse.pod b/doc/crypto/BN_mod_inverse.pod deleted file mode 100644 index b4792add82..0000000000 --- a/doc/crypto/BN_mod_inverse.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -BN_mod_inverse - compute inverse modulo n - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, - BN_CTX *ctx); - -=head1 DESCRIPTION - -BN_mod_inverse() computes the inverse of B<a> modulo B<n> -places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL, -a new B<BIGNUM> is created. - -B<ctx> is a previously allocated B<BN_CTX> used for temporary -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)>. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(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/doc/crypto/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod deleted file mode 100644 index bf1ef343cd..0000000000 --- a/doc/crypto/BN_mod_mul_montgomery.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=head1 NAME - -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 - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_MONT_CTX *BN_MONT_CTX_new(void); - 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); - -=head1 DESCRIPTION - -These functions implement Montgomery multiplication. They are used -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_set() sets up the I<mont> structure from the modulus I<m> -by precomputing its inverse and a value R. - -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>. - -BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1. - -BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R. -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. - -=head1 RETURN VALUES - -BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL -on error. - -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)>. - -=head1 WARNING - -The inputs must be reduced modulo B<m>, otherwise the result will be -outside the expected range. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>, -L<BN_CTX_new(3)> - -=head1 HISTORY - -BN_MONT_CTX_init() was removed 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/doc/crypto/BN_mod_mul_reciprocal.pod b/doc/crypto/BN_mod_mul_reciprocal.pod deleted file mode 100644 index d0536cd95b..0000000000 --- a/doc/crypto/BN_mod_mul_reciprocal.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, -BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using -reciprocal - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_RECP_CTX *BN_RECP_CTX_new(void); - 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_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp, - BN_CTX *ctx); - - int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_RECP_CTX *recp, BN_CTX *ctx); - -=head1 DESCRIPTION - -BN_mod_mul_reciprocal() can be used to perform an efficient -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_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 -integer. The result and the number of bits it was shifted left will -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 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_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)>. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>, -L<BN_CTX_new(3)> - -=head1 HISTORY - -BN_RECP_CTX_init() was removed 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/doc/crypto/BN_new.pod b/doc/crypto/BN_new.pod deleted file mode 100644 index 0277614276..0000000000 --- a/doc/crypto/BN_new.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_new(void); - - BIGNUM *BN_secure_new(void); - - void BN_clear(BIGNUM *a); - - void BN_free(BIGNUM *a); - - void BN_clear_free(BIGNUM *a); - -=head1 DESCRIPTION - -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 -to the value 0. - -BN_free() frees the components of the B<BIGNUM>, and if it was created -by BN_new(), also the structure itself. BN_clear_free() additionally -overwrites the data before the memory is returned to the system. -If B<a> is NULL, nothing is done. - -=head1 RETURN VALUES - -BN_new() and BN_secure_new() -return a pointer to the B<BIGNUM>. If the allocation fails, -they return B<NULL> and set an error code that can be obtained -by L<ERR_get_error(3)>. - -BN_clear(), BN_free() and BN_clear_free() have no return values. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(3)> - -=head1 HISTORY - -BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead. - -=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/doc/crypto/BN_num_bytes.pod b/doc/crypto/BN_num_bytes.pod deleted file mode 100644 index 4680cf7a71..0000000000 --- a/doc/crypto/BN_num_bytes.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - int BN_num_bytes(const BIGNUM *a); - - int BN_num_bits(const BIGNUM *a); - - int BN_num_bits_word(BN_ULONG w); - -=head1 DESCRIPTION - -BN_num_bytes() returns the size of a B<BIGNUM> in bytes. - -BN_num_bits_word() returns the number of significant bits in a word. -If we take 0x00000432 as an example, it returns 11, not 16, not 32. -Basically, except for a zero, it returns I<floor(log2(w))+1>. - -BN_num_bits() returns the number of significant bits in a B<BIGNUM>, -following the same principle as BN_num_bits_word(). - -BN_num_bytes() is a macro. - -=head1 RETURN VALUES - -The size. - -=head1 NOTES - -Some have tried using BN_num_bits() on individual numbers in RSA keys, -DH keys and DSA keys, and found that they don't always come up with -the number of bits they expected (something like 512, 1024, 2048, -...). This is because generating a number with some specific number -of bits doesn't always set the highest bits, thereby making the number -of I<significant> bits a little lower. If you want to know the "key -size" of such a key, either use functions like RSA_size(), DH_size() -and DSA_size(), or use BN_num_bytes() and multiply with 8 (although -there's no real guarantee that will match the "key size", just a lot -more probability). - -=head1 SEE ALSO - -L<bn(3)>, L<DH_size(3)>, L<DSA_size(3)>, -L<RSA_size(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/doc/crypto/BN_rand.pod b/doc/crypto/BN_rand.pod deleted file mode 100644 index ae15ada7e5..0000000000 --- a/doc/crypto/BN_rand.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - 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); - -=head1 DESCRIPTION - -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> -parameters, an error is returned. -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 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 -non-cryptographic purposes and for certain purposes in cryptographic -protocols, but usually not for key generation etc. - -BN_rand_range() generates a cryptographically strong pseudo-random -number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>. -BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(), -and hence numbers generated by it are not necessarily unpredictable. - -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)>. - -=head1 SEE ALSO - -L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>, -L<RAND_add(3)>, L<RAND_bytes(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/doc/crypto/BN_set_bit.pod b/doc/crypto/BN_set_bit.pod deleted file mode 100644 index 363227ade3..0000000000 --- a/doc/crypto/BN_set_bit.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift, -BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - 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); - -=head1 DESCRIPTION - -BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The -number is expanded if necessary. - -BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An -error occurs if B<a> is shorter than B<n> bits. - -BN_is_bit_set() tests if bit B<n> in B<a> is set. - -BN_mask_bits() truncates B<a> to an B<n> bit number -(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is -shorter than B<n> bits. - -BN_lshift() shifts B<a> left by B<n> bits and places the result in -B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts -B<a> left by one and places the result in B<r> (C<r=2*a>). - -BN_rshift() shifts B<a> right by B<n> bits and places the result in -B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts -B<a> right by one and places the result in B<r> (C<r=a/2>). - -For the shift functions, B<r> and B<a> may be the same variable. - -=head1 RETURN VALUES - -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)>. - -=head1 SEE ALSO - -L<bn(3)>, L<BN_num_bytes(3)>, L<BN_add(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/doc/crypto/BN_swap.pod b/doc/crypto/BN_swap.pod deleted file mode 100644 index fe7cc8482b..0000000000 --- a/doc/crypto/BN_swap.pod +++ /dev/null @@ -1,28 +0,0 @@ -=pod - -=head1 NAME - -BN_swap - exchange BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - void BN_swap(BIGNUM *a, BIGNUM *b); - -=head1 DESCRIPTION - -BN_swap() exchanges the values of I<a> and I<b>. - -L<bn(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/doc/crypto/BN_zero.pod b/doc/crypto/BN_zero.pod deleted file mode 100644 index fadc21b7fd..0000000000 --- a/doc/crypto/BN_zero.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment -operations - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - void 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); - -Deprecated: - - #if OPENSSL_API_COMPAT < 0x00908000L - int BN_zero(BIGNUM *a); - #endif - -=head1 DESCRIPTION - -BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and -B<w> respectively. BN_zero() and BN_one() are macros. - -BN_value_one() returns a B<BIGNUM> constant of value 1. This constant -is useful for use in comparisons and assignment. - -BN_get_word() returns B<a>, if it can be represented as an unsigned -long. - -=head1 RETURN VALUES - -BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot -be represented as an unsigned long. - -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 - -Someone might change the constant. - -If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an -unsigned long but this value is also returned on error. - -=head1 SEE ALSO - -L<bn(3)>, L<BN_bn2bin(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/doc/crypto/BUF_MEM_new.pod b/doc/crypto/BUF_MEM_new.pod deleted file mode 100644 index eb85bed896..0000000000 --- a/doc/crypto/BUF_MEM_new.pod +++ /dev/null @@ -1,77 +0,0 @@ -=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<out> -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(3)>, -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/doc/crypto/CMS_add0_cert.pod b/doc/crypto/CMS_add0_cert.pod deleted file mode 100644 index 5b0cc2a25c..0000000000 --- a/doc/crypto/CMS_add0_cert.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert); - int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert); - STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms); - - int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl); - int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl); - STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms); - - -=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. - -CMS_get1_certs() returns all certificates in B<cms>. - -CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls() -returns any CRLs in B<cms>. - -=head1 NOTES - -The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped -data or an error will be returned. - -For signed data certificates and CRLs are added to the B<certificates> and -B<crls> fields of SignedData structure. For enveloped data they are added to -B<OriginatorInfo>. - -As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it -must not be freed up after the call as opposed to CMS_add1_cert() where B<cert> -must be freed up. - -The same certificate or CRL must not be added to the same cms structure more -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. - -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 -in practice is if the B<cms> type is invalid. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, -L<CMS_sign(3)>, -L<CMS_encrypt(3)> - -=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/doc/crypto/CMS_add1_recipient_cert.pod b/doc/crypto/CMS_add1_recipient_cert.pod deleted file mode 100644 index 0dae5cf5fa..0000000000 --- a/doc/crypto/CMS_add1_recipient_cert.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags); - - CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType); - -=head1 DESCRIPTION - -CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped -data structure B<cms> as a KeyTransRecipientInfo structure. - -CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using -wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional -values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped -data structure B<cms> as a KEKRecipientInfo structure. - -The CMS_ContentInfo structure should be obtained from an initial call to -CMS_encrypt() with the flag B<CMS_PARTIAL> set. - -=head1 NOTES - -The main purpose of this function is to provide finer control over a CMS -enveloped data structure where the simpler CMS_encrypt() function defaults are -not appropriate. For example if one or more KEKRecipientInfo structures -need to be added. New attributes can also be added using the returned -CMS_RecipientInfo structure and the CMS attribute utility functions. - -OpenSSL will by default identify recipient certificates using issuer name -and serial number. If B<CMS_USE_KEYID> is set it will use the subject key -identifier value instead. An error occurs if all recipient certificates do not -have a subject key identifier extension. - -Currently only AES based key wrapping algorithms are supported for B<nid>, -specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. -If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used -consistent with B<keylen>. - -=head1 RETURN VALUES - -CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal -pointer to the CMS_RecipientInfo structure just added or NULL if an error -occurs. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_decrypt(3)>, -L<CMS_final(3)>, - -=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/doc/crypto/CMS_add1_signer.pod b/doc/crypto/CMS_add1_signer.pod deleted file mode 100644 index f4738e0637..0000000000 --- a/doc/crypto/CMS_add1_signer.pod +++ /dev/null @@ -1,106 +0,0 @@ -=pod - -=head1 NAME - -CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); - - int CMS_SignerInfo_sign(CMS_SignerInfo *si); - - -=head1 DESCRIPTION - -CMS_add1_signer() adds a signer with certificate B<signcert> and private -key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData -structure B<cms>. - -The CMS_ContentInfo structure should be obtained from an initial call to -CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a -valid CMS_ContentInfo SignedData structure. - -If the B<md> parameter is B<NULL> then the default digest for the public -key algorithm will be used. - -Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo -structure is not complete and must be finalized either by streaming (if -applicable) or a call to CMS_final(). - -The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo -structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags -are both set. - -=head1 NOTES - -The main purpose of CMS_add1_signer() is to provide finer control -over a CMS signed data structure where the simpler CMS_sign() function defaults -are not appropriate. For example if multiple signers or non default digest -algorithms are needed. New attributes can also be added using the returned -CMS_SignerInfo structure and the CMS attribute utility functions or the -CMS signed receipt request functions. - -Any of the following flags (ored together) can be passed in the B<flags> -parameter. - -If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content -digest value from the CMS_ContentInfo structure: to add a signer to an existing -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 -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. - -If B<CMS_NOCERTS> is set the signer's certificate will not be included in the -CMS_ContentInfo structure, the signer's certificate must still be supplied in -the 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 CMS signedAttributes including the -signing time, the CMS content type and the supported list of ciphers in an -SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes -will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are -omitted. - -OpenSSL will by default identify signing certificates using issuer name -and serial number. If B<CMS_USE_KEYID> is set it will use the subject key -identifier value instead. An error occurs if the signing certificate does not -have a subject key identifier extension. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 -bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. -If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is -not loaded. - -CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo -structure just added, this can be used to set additional attributes -before it is finalized. - -=head1 RETURN VALUES - -CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo -structure just added or NULL if an error occurs. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_sign(3)>, -L<CMS_final(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/doc/crypto/CMS_compress.pod b/doc/crypto/CMS_compress.pod deleted file mode 100644 index e40510831f..0000000000 --- a/doc/crypto/CMS_compress.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -CMS_compress - create a CMS CompressedData structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags); - -=head1 DESCRIPTION - -CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid> -is the compression algorithm to use or B<NID_undef> to use the default -algorithm (zlib compression). B<in> is the content to be compressed. -B<flags> is an optional set of flags. - -=head1 NOTES - -The only currently supported compression algorithm is zlib using the NID -NID_zlib_compression. - -If zlib support is not compiled into OpenSSL then CMS_compress() will return -an error. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are -prepended to the data. - -Normally the supplied content is translated into MIME canonical format (as -required by the S/MIME specifications) if B<CMS_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. If B<CMS_BINARY> is set then -B<CMS_TEXT> is ignored. - -If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is -returned suitable for streaming I/O: no data is read from the BIO B<in>. - -The compressed data is included in the CMS_ContentInfo structure, unless -B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in -practice and is not supported by SMIME_write_CMS(). - -=head1 NOTES - -If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is -B<not> complete and outputting its contents via a function that does not -properly finalize the B<CMS_ContentInfo> structure will give unpredictable -results. - -Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), -PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_CMS(). - -Additional compression parameters such as the zlib compression level cannot -currently be set. - -=head1 RETURN VALUES - -CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error -occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_uncompress(3)> - -=head1 HISTORY - -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/doc/crypto/CMS_decrypt.pod b/doc/crypto/CMS_decrypt.pod deleted file mode 100644 index b3b196c390..0000000000 --- a/doc/crypto/CMS_decrypt.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -CMS_decrypt - decrypt content from a CMS envelopedData structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags); - -=head1 DESCRIPTION - -CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData -structure. B<pkey> is the private key of the recipient, B<cert> is the -recipient's certificate, B<out> is a BIO to write the content to and -B<flags> is an optional set of flags. - -The B<dcont> parameter is used in the rare case where the encrypted content -is detached. It will normally be set to NULL. - -=head1 NOTES - -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. - -If B<cert> is set to NULL all possible recipients are tried. This case however -is problematic. To thwart the MMA attack (Bleichenbacher's attack on -PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or -not. If no recipient succeeds then a random symmetric key is used to decrypt -the content: this will typically output garbage and may (but is not guaranteed -to) ultimately return a padding error only. If CMS_decrypt() just returned an -error when all recipient encrypted keys failed to decrypt an attacker could -use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set -then the above behaviour is modified and an error B<is> returned if no -recipient encrypted key can be decrypted B<without> generating a random -content encryption key. Applications should use this flag with -B<extreme caution> especially in automated gateways as it can leave them -open to attack. - -It is possible to determine the correct recipient key by other means (for -example looking them up in a database) and setting them in the CMS structure -in advance using the CMS utility functions such as CMS_set1_pkey(). In this -case both B<cert> and B<pkey> should be set to NULL. - -To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() -and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and -B<cert> and B<pkey> set to NULL. - -The following flags can be passed in the B<flags> parameter. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -returned. - -=head1 RETURN VALUES - -CMS_decrypt() returns either 1 for success or 0 for failure. -The error can be obtained from ERR_get_error(3) - -=head1 BUGS - -The lack of single pass processing and the need to hold all data in memory as -mentioned in CMS_verify() also applies to CMS_decrypt(). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_encrypt(3)> - -=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/doc/crypto/CMS_encrypt.pod b/doc/crypto/CMS_encrypt.pod deleted file mode 100644 index 0ed42628c3..0000000000 --- a/doc/crypto/CMS_encrypt.pod +++ /dev/null @@ -1,104 +0,0 @@ -=pod - -=head1 NAME - -CMS_encrypt - create a CMS envelopedData structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags); - -=head1 DESCRIPTION - -CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs> -is a list of recipient certificates. B<in> is the content to be encrypted. -B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. - -=head1 NOTES - -Only certificates carrying RSA keys are supported so the recipient certificates -supplied to this function must all contain RSA public keys, though they do not -have to be signed using the RSA algorithm. - -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. - -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 -by storing the S/MIME signed message in a memory BIO and passing it to -CMS_encrypt(). - -The following flags can be passed in the B<flags> parameter. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are -prepended to the data. - -Normally the supplied content is translated into MIME canonical format (as -required by the S/MIME specifications) if B<CMS_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. If B<CMS_BINARY> is set then -B<CMS_TEXT> is ignored. - -OpenSSL will by default identify recipient certificates using issuer name -and serial number. If B<CMS_USE_KEYID> is set it will use the subject key -identifier value instead. An error occurs if all recipient certificates do not -have a subject key identifier extension. - -If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is -returned suitable for streaming I/O: no data is read from the BIO B<in>. - -If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is -returned to which additional recipients and attributes can be added before -finalization. - -The data being encrypted is included in the CMS_ContentInfo structure, unless -B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in -practice and is not supported by SMIME_write_CMS(). - -=head1 NOTES - -If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is -B<not> complete and outputting its contents via a function that does not -properly finalize the B<CMS_ContentInfo> structure will give unpredictable -results. - -Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), -PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_CMS(). - -The recipients specified in B<certs> use a CMS KeyTransRecipientInfo info -structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL> -and CMS_add0_recipient_key(). - -The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients -added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key(). - -=head1 RETURN VALUES - -CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error -occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_decrypt(3)> - -=head1 HISTORY - -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/doc/crypto/CMS_final.pod b/doc/crypto/CMS_final.pod deleted file mode 100644 index 264fe7bc3b..0000000000 --- a/doc/crypto/CMS_final.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -CMS_final - finalise a CMS_ContentInfo structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); - -=head1 DESCRIPTION - -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 -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. - -=head1 NOTES - -This function will normally be called when the B<CMS_PARTIAL> flag is used. It -should only be used when streaming is not performed because the streaming -I/O functions perform finalisation operations internally. - -=head1 RETURN VALUES - -CMS_final() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_sign(3)>, -L<CMS_encrypt(3)> - -=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/doc/crypto/CMS_get0_RecipientInfos.pod b/doc/crypto/CMS_get0_RecipientInfos.pod deleted file mode 100644 index 6c33c224e9..0000000000 --- a/doc/crypto/CMS_get0_RecipientInfos.pod +++ /dev/null @@ -1,130 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms); - int CMS_RecipientInfo_type(CMS_RecipientInfo *ri); - - int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); - int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert); - int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey); - - int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype); - int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen); - int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen); - - int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); - int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); - -=head1 DESCRIPTION - -The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo -structures associated with a CMS EnvelopedData structure. - -CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>. -It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, -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>. - -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. -It returns zero if the comparison is successful and non zero if not. - -CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with -the CMS_RecipientInfo structure B<ri>, which must be of type -CMS_RECIPINFO_TRANS. - -CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the -CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any -of the remaining parameters can be NULL if the application is not interested in -the value of a field. Where a field is optional and absent NULL will be written -to the corresponding parameter. The keyEncryptionAlgorithm field is written to -B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if -present is written to B<pdate>, if the B<other> field is present the components -B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and -B<pothertype>. - -CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen> -parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>, -which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is -successful and non zero if not. - -CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length -B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type -CMS_RECIPINFO_KEK. - -CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure -B<ri> in structure B<cms>. A key must have been associated with the structure -first. - -CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure -B<ri> in structure B<cms>. A key must have been associated with the structure -first and the content encryption key must be available: for example by a -previous call to CMS_RecipientInfo_decrypt(). - -=head1 NOTES - -The main purpose of these functions is to enable an application to lookup -recipient keys using any appropriate technique when the simpler method -of CMS_decrypt() is not appropriate. - -In typical usage and application will retrieve all CMS_RecipientInfo structures -using CMS_get0_RecipientInfos() and check the type of each using -CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure -can be ignored or its key identifier data retrieved using an appropriate -function. Then if the corresponding secret or private key can be obtained by -any appropriate means it can then associated with the structure and -CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called -with a NULL key to decrypt the enveloped content. - -The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an -existing enveloped data structure. Typically an application will first decrypt -an appropriate CMS_RecipientInfo structure to make the content encrypt key -available, it will then add a new recipient using a function such as -CMS_add1_recipient_cert() and finally encrypt the content encryption key -using CMS_RecipientInfo_encrypt(). - -=head1 RETURN VALUES - -CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if -an error occurs. - -CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), -CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and -CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. -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)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_decrypt(3)> - -=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/doc/crypto/CMS_get0_SignerInfos.pod b/doc/crypto/CMS_get0_SignerInfos.pod deleted file mode 100644 index c8071591f3..0000000000 --- a/doc/crypto/CMS_get0_SignerInfos.pod +++ /dev/null @@ -1,89 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/cms.h> - - STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms); - - int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); - ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si); - int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert); - void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer); - -=head1 DESCRIPTION - -The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures -associated with a CMS signedData structure. - -CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier -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 -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. - -CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer -identifier B<si>. It returns zero if the comparison is successful and non zero -if not. - -CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to -B<signer>. - -=head1 NOTES - -The main purpose of these functions is to enable an application to lookup -signers certificates using any appropriate technique when the simpler method -of CMS_verify() is not appropriate. - -In typical usage and application will retrieve all CMS_SignerInfo structures -using CMS_get0_SignerInfo() and retrieve the identifier information using -CMS. It will then obtain the signer certificate by some unspecified means -(or return and error if it cannot be found) and set it using -CMS_SignerInfo_set1_signer_cert(). - -Once all signer certificates have been set CMS_verify() can be used. - -Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if -there are no signers this is not a problem in practice because the only -error which can occur is if the B<cms> structure is not of type signedData -due to application error. - -=head1 RETURN VALUES - -CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there -are no signers or an error occurs. - -CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure. - -CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non -zero otherwise. - -CMS_SignerInfo_set1_signer_cert() does not return a value. - -Any error can be obtained from L<ERR_get_error(3)> - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_verify(3)> - -=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/doc/crypto/CMS_get0_type.pod b/doc/crypto/CMS_get0_type.pod deleted file mode 100644 index cad8d3f662..0000000000 --- a/doc/crypto/CMS_get0_type.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -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(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); - -=head1 DESCRIPTION - -CMS_get0_type() returns the content type of a CMS_ContentInfo structure as -and ASN1_OBJECT pointer. An application can then decide how to process the -CMS_ContentInfo structure based on this value. - -CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo -structure. It should be called with CMS functions with the B<CMS_PARTIAL> -flag and B<before> the structure is finalised, otherwise the results are -undefined. - -ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded -content type. - -CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer -containing the embedded content. - -=head1 NOTES - -As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and -CMS_get0_content() return internal pointers which should B<not> be freed up. -CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up -after use. - -The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value -using OBJ_obj2nid(). For the currently supported content types the following -values are returned: - - NID_pkcs7_data - NID_pkcs7_signed - NID_pkcs7_digest - NID_id_smime_ct_compressedData: - NID_pkcs7_encrypted - NID_pkcs7_enveloped - -The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING> -content pointer. That means that for example: - - ASN1_OCTET_STRING **pconf = CMS_get0_content(cms); - -B<*pconf> could be NULL if there is no embedded content. Applications can -access, modify or create the embedded content in a B<CMS_ContentInfo> structure -using this function. Applications usually will not need to modify the -embedded content as it is normally set by higher level functions. - -=head1 RETURN VALUES - -CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure. - -CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The -error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)> - -=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/doc/crypto/CMS_get1_ReceiptRequest.pod b/doc/crypto/CMS_get1_ReceiptRequest.pod deleted file mode 100644 index 79f5f4232d..0000000000 --- a/doc/crypto/CMS_get1_ReceiptRequest.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); - int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); - int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); - void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto); - -=head1 DESCRIPTION - -CMS_ReceiptRequest_create0() creates a signed receipt request structure. The -B<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set -to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL -the allOrFirstTier option in B<receiptsFrom> is used and set to the value of -the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList> -option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the -B<receiptsTo> field value. - -The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr> -to SignerInfo structure B<si>. - -int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if -any is found it is decoded and written to B<prr>. - -CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. -The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier> -option of B<receiptsFrom> is used its value is copied to B<pallorfirst> -otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo> -parameter is copied to B<prto>. - -=head1 NOTES - -For more details of the meaning of the fields see RFC2634. - -The contents of a signed receipt should only be considered meaningful if the -corresponding CMS_ContentInfo structure can be successfully verified using -CMS_verify(). - -=head1 RETURN VALUES - -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. - -CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and -decoded. It returns 0 if a signed receipt request is not present and -1 if -it is present but malformed. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_sign(3)>, -L<CMS_sign_receipt(3)>, L<CMS_verify(3)> -L<CMS_verify_receipt(3)> - -=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/doc/crypto/CMS_sign.pod b/doc/crypto/CMS_sign.pod deleted file mode 100644 index 396deef772..0000000000 --- a/doc/crypto/CMS_sign.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -CMS_sign - create a CMS SignedData structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags); - -=head1 DESCRIPTION - -CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is -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 CMS -structure (for example any intermediate CAs in the chain). Any or all of -these parameters can be B<NULL>, see B<NOTES> below. - -The data to be signed is read from BIO B<data>. - -B<flags> is an optional set of flags. - -=head1 NOTES - -Any of the following flags (ored together) can be passed in the B<flags> -parameter. - -Many S/MIME clients expect the signed content to include valid MIME headers. If -the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended -to the data. - -If B<CMS_NOCERTS> is set the signer's certificate will not be included in the -CMS_ContentInfo structure, the signer's certificate must still be supplied in -the 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 data being signed is included in the CMS_ContentInfo structure, unless -B<CMS_DETACHED> is set in which case it is omitted. This is used for -CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed -messages for example. - -Normally the supplied content is translated into MIME canonical format (as -required by the S/MIME specifications) if B<CMS_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 CMS signedAttributes including the -signing time, the CMS content type and the supported list of ciphers in an -SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes -will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are -omitted. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 -bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. -If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is -not loaded. - -OpenSSL will by default identify signing certificates using issuer name -and serial number. If B<CMS_USE_KEYID> is set it will use the subject key -identifier value instead. An error occurs if the signing certificate does not -have a subject key identifier extension. - -If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo> -structure is just initialized ready to perform the signing operation. The -signing is however B<not> performed and the data to be signed is not read from -the B<data> parameter. Signing is deferred until after the data has been -written. In this way data can be signed in a single pass. - -If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is -output to which additional signers and capabilities can be added before -finalization. - -If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is -B<not> complete and outputting its contents via a function that does not -properly finalize the B<CMS_ContentInfo> structure will give unpredictable -results. - -Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), -PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_CMS(). - -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. - -If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is -output. - -The function CMS_sign() is a basic CMS signing function whose output will be -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. CMS_final() must then be called to finalize the -structure if streaming is not enabled. - -=head1 BUGS - -Some attributes such as counter signatures are not supported. - -=head1 RETURN VALUES - -CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error -occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_verify(3)> - -=head1 HISTORY - -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/doc/crypto/CMS_sign_receipt.pod b/doc/crypto/CMS_sign_receipt.pod deleted file mode 100644 index 8ea6df1fbc..0000000000 --- a/doc/crypto/CMS_sign_receipt.pod +++ /dev/null @@ -1,50 +0,0 @@ -=pod - -=head1 NAME - -CMS_sign_receipt - create a CMS signed receipt - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags); - -=head1 DESCRIPTION - -CMS_sign_receipt() creates and returns a CMS signed receipt structure. B<si> is -the B<CMS_SignerInfo> structure containing the signed receipt request. -B<signcert> is 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 CMS structure (for example any intermediate CAs in the chain). - -B<flags> is an optional set of flags. - -=head1 NOTES - -This functions behaves in a similar way to CMS_sign() except the flag values -B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM> -are not supported since they do not make sense in the context of signed -receipts. - -=head1 RETURN VALUES - -CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if -an error occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, -L<CMS_verify_receipt(3)>, -L<CMS_sign(3)> - -=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/doc/crypto/CMS_uncompress.pod b/doc/crypto/CMS_uncompress.pod deleted file mode 100644 index 80f9c0d168..0000000000 --- a/doc/crypto/CMS_uncompress.pod +++ /dev/null @@ -1,59 +0,0 @@ -=pod - -=head1 NAME - -CMS_uncompress - uncompress a CMS CompressedData structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags); - -=head1 DESCRIPTION - -CMS_uncompress() extracts and uncompresses the content from a CMS -CompressedData structure B<cms>. B<data> is a BIO to write the content to and -B<flags> is an optional set of flags. - -The B<dcont> parameter is used in the rare case where the compressed content -is detached. It will normally be set to NULL. - -=head1 NOTES - -The only currently supported compression algorithm is zlib: if the structure -indicates the use of any other algorithm an error is returned. - -If zlib support is not compiled into OpenSSL then CMS_uncompress() will always -return an error. - -The following flags can be passed in the B<flags> parameter. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -returned. - -=head1 RETURN VALUES - -CMS_uncompress() returns either 1 for success or 0 for failure. The error can -be obtained from ERR_get_error(3) - -=head1 BUGS - -The lack of single pass processing and the need to hold all data in memory as -mentioned in CMS_verify() also applies to CMS_decompress(). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_compress(3)> - -=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/doc/crypto/CMS_verify.pod b/doc/crypto/CMS_verify.pod deleted file mode 100644 index c2ff57bcf2..0000000000 --- a/doc/crypto/CMS_verify.pod +++ /dev/null @@ -1,131 +0,0 @@ -=pod - -=head1 NAME - -CMS_verify, CMS_get0_signers - verify a CMS SignedData structure - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags); - - STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); - -=head1 DESCRIPTION - -CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo -structure to verify. B<certs> is a set of certificates in which to search for -the signing certificate(s). B<store> is a trusted certificate store used for -chain verification. B<indata> is the detached content if the content is not -present in B<cms>. The content is written to B<out> if it is not NULL. - -B<flags> is an optional set of flags, which can be used to modify the verify -operation. - -CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must -be called after a successful CMS_verify() operation. - -=head1 VERIFY PROCESS - -Normally the verify process proceeds as follows. - -Initially some sanity checks are performed on B<cms>. The type of B<cms> 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>. - -An attempt is made to locate all the signing certificate(s), first looking in -the B<certs> parameter (if it is not NULL) and then looking in any -certificates contained in the B<cms> structure itself. If any signing -certificate cannot be located the operation fails. - -Each signing certificate is chain verified using the B<smimesign> purpose and -the supplied trusted certificate store. Any internal certificates in the message -are used as untrusted CAs. If CRL checking is enabled in B<store> any internal -CRLs are used in addition to attempting to look them up in B<store>. If any -chain verify fails an error code is returned. - -Finally the signed content is read (and written to B<out> is it is not NULL) -and the signature's checked. - -If all signature's verify correctly then the function is successful. - -Any of the following flags (ored together) can be passed in the B<flags> -parameter to change the default verify behaviour. - -If B<CMS_NOINTERN> is set the certificates in the message itself are not -searched when locating the signing certificate(s). This means that all the -signing certificates must be in the B<certs> parameter. - -If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any -CRLs in the message itself are ignored. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -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 -verified. - -If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. - -=head1 NOTES - -One application of B<CMS_NOINTERN> is to only accept messages signed by -a small number of certificates. The acceptable certificates would be passed -in the B<certs> parameter. In this case if the signer is not one of the -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 -lookup certificates in a database or perform customised verification. This -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 -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. - -Chain verification should arguably be performed using the signing time rather -than the current time. However since the signing time is supplied by the -signer it cannot be trusted without additional evidence (such as a trusted -timestamp). - -=head1 RETURN VALUES - -CMS_verify() returns 1 for a successful verification and zero if an error -occurred. - -CMS_get0_signers() returns all signers or NULL if an error occurred. - -The error can be obtained from L<ERR_get_error(3)> - -=head1 BUGS - -The trusted certificate store is not searched for the signing certificate, -this is primarily due to the inadequacies of the current B<X509_STORE> -functionality. - -The lack of single pass processing means that the signed content must all -be held in memory if it is not detached. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_sign(3)> - -=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/doc/crypto/CMS_verify_receipt.pod b/doc/crypto/CMS_verify_receipt.pod deleted file mode 100644 index 193241c620..0000000000 --- a/doc/crypto/CMS_verify_receipt.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -CMS_verify_receipt - verify a CMS signed receipt - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags); - -=head1 DESCRIPTION - -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). - -B<flags> is an optional set of flags, which can be used to modify the verify -operation. - -=head1 NOTES - -This functions behaves in a similar way to CMS_verify() except the flag values -B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> are not -supported since they do not make sense in the context of signed receipts. - -=head1 RETURN VALUES - -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)> - -=head1 SEE ALSO - -L<ERR_get_error(3)>, -L<CMS_sign_receipt(3)>, -L<CMS_verify(3)>, - -=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/doc/crypto/CONF_modules_free.pod b/doc/crypto/CONF_modules_free.pod deleted file mode 100644 index ac59f3736a..0000000000 --- a/doc/crypto/CONF_modules_free.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -CONF_modules_free, CONF_modules_finish, CONF_modules_unload - -OpenSSL configuration cleanup functions - -=head1 SYNOPSIS - - #include <openssl/conf.h> - - 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 -configuration modules. - -CONF_modules_finish() calls each configuration modules B<finish> handler -to free up any configuration that module may have performed. - -CONF_modules_unload() finishes and unloads configuration modules. If -B<all> is set to B<0> only modules loaded from DSOs will be unloads. If -B<all> is B<1> all modules, including builtin modules will be unloaded. - -=head1 NOTES - -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 - -None of the functions return a value. - -=head1 SEE ALSO - -L<conf(5)>, L<OPENSSL_config(3)>, -L<CONF_modules_load_file(3)> - -=head1 HISTORY - -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/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod deleted file mode 100644 index 9e4071f2b3..0000000000 --- a/doc/crypto/CONF_modules_load_file.pod +++ /dev/null @@ -1,136 +0,0 @@ -=pod - -=head1 NAME - -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); - int CONF_modules_load(const CONF *cnf, const char *appname, - unsigned long flags); - -=head1 DESCRIPTION - -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 customized using B<flags>. - -CONF_modules_load() is identical to CONF_modules_load_file() except it -reads configuration information from B<cnf>. - -=head1 NOTES - -The following B<flags> are currently recognized: - -B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual -configuration modules are ignored. If not set the first module error is -considered fatal and no further modules are loaded. - -Normally any modules errors will add error information to the error queue. If -B<CONF_MFLAGS_SILENT> is set no error information is added. - -If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is -disabled. - -B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file() -ignore missing configuration files. Normally a missing configuration file -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. - -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 -this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set. - -Errors during configuration may also be handled differently by different -applications. For example in some cases an error may simply print out a warning -message and the application continue. In other cases an application might -consider a configuration file error as fatal and exit immediately. - -Applications can use the CONF_modules_load() function if they wish to load a -configuration file themselves and have finer control over how errors are -treated. - -=head1 EXAMPLES - -Load a configuration file and print out any errors and exit (missing file -considered fatal): - - if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { - fprintf(stderr, "FATAL: error loading configuration file\n"); - ERR_print_errors_fp(stderr); - exit(1); - } - -Load default configuration file using the section indicated by "myapp", -tolerate missing files, but exit on other errors: - - if (CONF_modules_load_file(NULL, "myapp", - CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { - fprintf(stderr, "FATAL: error loading configuration file\n"); - ERR_print_errors_fp(stderr); - exit(1); - } - -Load custom configuration file and section, only print warnings on error, -missing configuration file ignored: - - if (CONF_modules_load_file("/something/app.cnf", "myapp", - CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { - fprintf(stderr, "WARNING: error loading configuration file\n"); - ERR_print_errors_fp(stderr); - } - -Load and parse configuration file manually, custom error handling: - - FILE *fp; - CONF *cnf = NULL; - long eline; - fp = fopen("/somepath/app.cnf", "r"); - if (fp == NULL) { - fprintf(stderr, "Error opening configuration file\n"); - /* Other missing configuration file behaviour */ - } else { - cnf = NCONF_new(NULL); - if (NCONF_load_fp(cnf, fp, &eline) == 0) { - fprintf(stderr, "Error on line %ld of configuration file\n", eline); - ERR_print_errors_fp(stderr); - /* Other malformed configuration file behaviour */ - } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { - fprintf(stderr, "Error configuring application\n"); - ERR_print_errors_fp(stderr); - /* Other configuration error behaviour */ - } - fclose(fp); - NCONF_free(cnf); - } - -=head1 RETURN VALUES - -These functions return 1 for success and a zero or negative value for -failure. If module errors are not ignored the return code will reflect the -return value of the failing module (this will always be zero or negative). - -=head1 SEE ALSO - -L<conf(5)>, L<OPENSSL_config(3)>, -L<CONF_free(3)>, L<err(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/doc/crypto/CRYPTO_THREAD_run_once.pod b/doc/crypto/CRYPTO_THREAD_run_once.pod deleted file mode 100644 index 7795a04477..0000000000 --- a/doc/crypto/CRYPTO_THREAD_run_once.pod +++ /dev/null @@ -1,163 +0,0 @@ -=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 4 - -=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(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/doc/crypto/CRYPTO_get_ex_new_index.pod b/doc/crypto/CRYPTO_get_ex_new_index.pod deleted file mode 100644 index 98085f525b..0000000000 --- a/doc/crypto/CRYPTO_get_ex_new_index.pod +++ /dev/null @@ -1,161 +0,0 @@ -=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 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, 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 - 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> and B<SSL_SESSION> objects. The B<to> and B<from> parameters -are pointers to the destination and source B<CRYPTO_EX_DATA> structures, -respectively. The B<srcp> parameter is a pointer to the source exdata. -When the dup_func() returns, the value in B<srcp> is copied to the -destination ex_data. If the pointer contained in B<srcp> 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. - -=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-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/doc/crypto/CTLOG_STORE_get0_log_by_id.pod b/doc/crypto/CTLOG_STORE_get0_log_by_id.pod deleted file mode 100644 index c517e95e0f..0000000000 --- a/doc/crypto/CTLOG_STORE_get0_log_by_id.pod +++ /dev/null @@ -1,49 +0,0 @@ -=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/doc/crypto/CTLOG_STORE_new.pod b/doc/crypto/CTLOG_STORE_new.pod deleted file mode 100644 index 2a38f263ba..0000000000 --- a/doc/crypto/CTLOG_STORE_new.pod +++ /dev/null @@ -1,79 +0,0 @@ -=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/doc/crypto/CTLOG_new.pod b/doc/crypto/CTLOG_new.pod deleted file mode 100644 index ccda6b9c41..0000000000 --- a/doc/crypto/CTLOG_new.pod +++ /dev/null @@ -1,72 +0,0 @@ -=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/doc/crypto/CT_POLICY_EVAL_CTX_new.pod b/doc/crypto/CT_POLICY_EVAL_CTX_new.pod deleted file mode 100644 index 62792992e2..0000000000 --- a/doc/crypto/CT_POLICY_EVAL_CTX_new.pod +++ /dev/null @@ -1,96 +0,0 @@ -=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 - -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); - -=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 signature must be verified. This requires: - -=over - -=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) - -=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 - -=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. - -=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(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/doc/crypto/DEFINE_STACK_OF.pod b/doc/crypto/DEFINE_STACK_OF.pod deleted file mode 100644 index ae443b0a3b..0000000000 --- a/doc/crypto/DEFINE_STACK_OF.pod +++ /dev/null @@ -1,233 +0,0 @@ -=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<compar>. -If B<compar> 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<compar>. -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() and sk_TYPE_find_ex() search B<sk> using the supplied -comparison function for an element matching B<ptr>. sk_TYPE_find() returns -the index of the first matching element or B<-1> if there is no match. -sk_TYPE_find_ex() returns a matching element or the nearest element that -does not match B<ptr>. Note: if a comparison function is set then B<sk> is -sorted before the search which may change its order. If no comparison -function is set then a linear search is made for a pointer matching B<ptr> -and the stack is not reordered. - -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/doc/crypto/DES_random_key.pod b/doc/crypto/DES_random_key.pod deleted file mode 100644 index 0131093ba9..0000000000 --- a/doc/crypto/DES_random_key.pod +++ /dev/null @@ -1,310 +0,0 @@ -=pod - -=head1 NAME - -DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, -DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, -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_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 encryption - -=head1 SYNOPSIS - - #include <openssl/des.h> - - void DES_random_key(DES_cblock *ret); - - int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule); - int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule); - int DES_set_key_checked(const_DES_cblock *key, - DES_key_schedule *schedule); - void DES_set_key_unchecked(const_DES_cblock *key, - DES_key_schedule *schedule); - - 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, - DES_key_schedule *ks, int enc); - 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, - 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, - int enc); - void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, - int numbits, long length, DES_key_schedule *schedule, - DES_cblock *ivec, int enc); - 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, - int enc); - void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *schedule, DES_cblock *ivec, - int *num, int enc); - void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out, - 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, - const_DES_cblock *inw, const_DES_cblock *outw, int enc); - - void DES_ede2_cbc_encrypt(const unsigned char *input, - unsigned char *output, long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_cblock *ivec, int enc); - void DES_ede2_cfb64_encrypt(const unsigned char *in, - unsigned char *out, long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc); - void DES_ede2_ofb64_encrypt(const unsigned char *in, - unsigned char *out, long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_cblock *ivec, int *num); - - void DES_ede3_cbc_encrypt(const unsigned char *input, - 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_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, - DES_cblock *ivec, int *num); - - 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[], - 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, - DES_cblock *key2); - - char *DES_fcrypt(const char *buf, const char *salt, char *ret); - char *DES_crypt(const char *buf, const char *salt); - -=head1 DESCRIPTION - -This library contains a fast implementation of the DES encryption -algorithm. - -There are two phases to the use of DES encryption. The first is the -generation of a I<DES_key_schedule> from a key, the second is the -actual encryption. A DES key is of type I<DES_cblock>. This type is -consists of 8 bytes with odd parity. The least significant bit in -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)>). 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 -architecture dependent I<DES_key_schedule> via the -DES_set_key_checked() or DES_set_key_unchecked() function. - -DES_set_key_checked() will check that the key passed is of odd parity -and is not a week or semi-weak key. If the parity is wrong, then -1 -is returned. If the key is a weak key, then -2 is returned. If an -error is returned, the key schedule is not generated. - -DES_set_key() works like -DES_set_key_checked() if the I<DES_check_key> flag is non-zero, -otherwise like DES_set_key_unchecked(). These functions are available -for compatibility; it is recommended to use a function that does not -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. - -The following routines mostly operate on an input and output stream of -I<DES_cblock>s. - -DES_ecb_encrypt() is the basic DES encryption routine that encrypts or -decrypts a single 8-byte I<DES_cblock> in I<electronic code book> -(ECB) mode. It always transforms the input data, pointed to by -I<input>, into the output data, pointed to by the I<output> argument. -If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input> -(cleartext) is encrypted in to the I<output> (ciphertext) using the -key_schedule specified by the I<schedule> argument, previously set via -I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now -ciphertext) is decrypted into the I<output> (now cleartext). Input -and output may overlap. DES_ecb_encrypt() does not return a value. - -DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using -three-key Triple-DES encryption in ECB mode. This involves encrypting -the input with I<ks1>, decrypting with the key schedule I<ks2>, and -then encrypting with I<ks3>. This routine greatly reduces the chances -of brute force breaking of DES and has the advantage of if I<ks1>, -I<ks2> and I<ks3> are the same, it is equivalent to just encryption -using ECB mode and I<ks1> as the key. - -The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES -encryption by using I<ks1> for the final encryption. - -DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining> -(CBC) mode of DES. If the I<encrypt> argument is non-zero, the -routine cipher-block-chain encrypts the cleartext data pointed to by -the I<input> argument into the ciphertext pointed to by the I<output> -argument, using the key schedule provided by the I<schedule> argument, -and initialization vector provided by the I<ivec> argument. If the -I<length> argument is not an integral multiple of eight bytes, the -last block is copied to a temporary area and zero filled. The output -is always an integral multiple of eight bytes. - -DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and -I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret -(unlike the iv) and are as such, part of the key. So the key is sort -of 24 bytes. This is much better than CBC DES. - -DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with -three keys. This means that each DES operation inside the CBC mode is -an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL. - -The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by -reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>. -This form of Triple-DES is used by the RSAREF library. - -DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block -chaining mode used by Kerberos v4. Its parameters are the same as -DES_ncbc_encrypt(). - -DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This -method takes an array of characters as input and outputs and array of -characters. It does not require any padding to 8 character groups. -Note: the I<ivec> variable is changed and the new changed value needs to -be passed to the next call to this function. Since this function runs -a complete DES ECB encryption per I<numbits>, this function is only -suggested for use when sending small numbers of characters. - -DES_cfb64_encrypt() -implements CFB mode of DES with 64bit feedback. Why is this -useful you ask? Because this routine will allow you to encrypt an -arbitrary number of bytes, no 8 byte padding. Each call to this -routine will encrypt the input bytes to output and then update ivec -and num. num contains 'how far' we are though ivec. If this does -not make much sense, read more about cfb mode of DES :-). - -DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as -DES_cfb64_encrypt() except that Triple-DES is used. - -DES_ofb_encrypt() encrypts using output feedback mode. This method -takes an array of characters as input and outputs and array of -characters. It does not require any padding to 8 character groups. -Note: the I<ivec> variable is changed and the new changed value needs to -be passed to the next call to this function. Since this function runs -a complete DES ECB encryption per numbits, this function is only -suggested for use when sending small numbers of characters. - -DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output -Feed Back mode. - -DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as -DES_ofb64_encrypt(), using Triple-DES. - -The following functions are included in the DES library for -compatibility with the MIT Kerberos library. - -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)> 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 -input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is -non-NULL, the 8 bytes generated by each pass are written into -I<output>. - -The following are DES-based transformations: - -DES_fcrypt() is a fast version of the Unix crypt(3) function. This -version takes only a small amount of space relative to other fast -crypt() implementations. This is different to the normal crypt in -that the third parameter is the buffer that the return value is -written into. It needs to be at least 14 bytes long. This function -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 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) -using I<sched> for the key and I<iv> as a starting vector. The actual -data send down I<fd> consists of 4 bytes (in network byte order) -containing the length of the following encrypted data. The encrypted -data then follows, padded with random data out to a multiple of 8 -bytes. - -=head1 BUGS - -DES_3cbc_encrypt() is flawed and must not be used in applications. - -DES_cbc_encrypt() does not modify B<ivec>; use DES_ncbc_encrypt() -instead. - -DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits. -What this means is that if you set numbits to 12, and length to 2, the -first 12 bits will come from the 1st input byte and the low half of -the second input byte. The second 12 bits will have the low 8 bits -taken from the 3rd input byte and the top 4 bits taken from the 4th -input byte. The same holds for output. This function has been -implemented this way because most people will be using a multiple of 8 -and because once you get into pulling bytes input bytes apart things -get ugly! - -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 NOTES - -The B<des> library was written to be source code compatible with -the MIT Kerberos library. - -Applications should use the higher level functions -L<EVP_EncryptInit(3)> etc. instead of calling these -functions directly. - -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 - -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/doc/crypto/DH_generate_key.pod b/doc/crypto/DH_generate_key.pod deleted file mode 100644 index de0847a94d..0000000000 --- a/doc/crypto/DH_generate_key.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - int DH_generate_key(DH *dh); - - int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); - -=head1 DESCRIPTION - -DH_generate_key() performs the first step of a Diffie-Hellman key -exchange by generating private and public DH values. By calling -DH_compute_key(), these are combined with the other party's public -value to compute the shared key. - -DH_generate_key() expects B<dh> to contain the shared parameters -B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value -unless B<dh-E<gt>priv_key> is already set, and computes the -corresponding public value B<dh-E<gt>pub_key>, which can then be -published. - -DH_compute_key() computes the shared secret from the private DH value -in B<dh> and the other party's public value in B<pub_key> and stores -it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory. - -=head1 RETURN VALUES - -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)>. - -=head1 SEE ALSO - -L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>, L<DH_size(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/doc/crypto/DH_generate_parameters.pod b/doc/crypto/DH_generate_parameters.pod deleted file mode 100644 index b71497baaf..0000000000 --- a/doc/crypto/DH_generate_parameters.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -DH_generate_parameters_ex, DH_generate_parameters, -DH_check - 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_check(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 - -DH_generate_parameters_ex() generates Diffie-Hellman parameters that can -be shared among a group of users, and stores them in the provided B<DH> -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. - -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)> 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)> for information on -the BN_GENCB_call() function. - -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() (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)>. - -=head1 NOTES - -DH_generate_parameters_ex() and DH_generate_parameters() may run for several -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 SEE ALSO - -L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>, -L<DH_free(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/doc/crypto/DH_get0_pqg.pod b/doc/crypto/DH_get0_pqg.pod deleted file mode 100644 index 79647bf890..0000000000 --- a/doc/crypto/DH_get0_pqg.pod +++ /dev/null @@ -1,112 +0,0 @@ -=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(). The public -key must be non-NULL the first time this function is called on a given DH -object. The private key may be NULL. On subsequent calls, either may be NULL, -which means the corresponding DH field is left untouched. As for 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 version 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/doc/crypto/DH_get_1024_160.pod b/doc/crypto/DH_get_1024_160.pod deleted file mode 100644 index 4044f10418..0000000000 --- a/doc/crypto/DH_get_1024_160.pod +++ /dev/null @@ -1,74 +0,0 @@ -=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/doc/crypto/DH_meth_new.pod b/doc/crypto/DH_meth_new.pod deleted file mode 100644 index bcf559215f..0000000000 --- a/doc/crypto/DH_meth_new.pod +++ /dev/null @@ -1,156 +0,0 @@ -=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 version 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/doc/crypto/DH_new.pod b/doc/crypto/DH_new.pod deleted file mode 100644 index 959a470ec4..0000000000 --- a/doc/crypto/DH_new.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -DH_new, DH_free - allocate and free DH objects - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - DH* DH_new(void); - - void DH_free(DH *dh); - -=head1 DESCRIPTION - -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)>. Otherwise it returns -a pointer to the newly allocated structure. - -DH_free() returns no value. - -=head1 SEE ALSO - -L<dh(3)>, L<ERR_get_error(3)>, -L<DH_generate_parameters(3)>, -L<DH_generate_key(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/doc/crypto/DH_set_method.pod b/doc/crypto/DH_set_method.pod deleted file mode 100644 index cd75a9b549..0000000000 --- a/doc/crypto/DH_set_method.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -DH_set_default_method, DH_get_default_method, -DH_set_method, DH_new_method, DH_OpenSSL - select DH method - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - 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); - -=head1 DESCRIPTION - -A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman -operations. By modifying the method, alternative implementations -such as hardware accelerators may be used. IMPORTANT: See the NOTES section for -important information about how these DH API functions are affected by the use -of B<ENGINE> API calls. - -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 -as a default for DH, so this function is no longer recommended. - -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 -API is being used, so this function is no longer recommended. - -DH_set_method() selects B<meth> to perform all operations using the key B<dh>. -This will replace the DH_METHOD used by the DH key and if the previous method -was supplied by an ENGINE, the handle to that ENGINE will be released during the -change. It is possible to have DH keys that only work with certain DH_METHOD -implementations (eg. from an ENGINE module that supports embedded -hardware-protected keys), and in such cases attempting to change the DH_METHOD -for the key can have unexpected results. - -DH_new_method() allocates and initializes a DH structure so that B<engine> will -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. - -A new DH_METHOD object may be constructed using DH_meth_new() (see -L<DH_meth_new(3)>). - -=head1 RETURN VALUES - -DH_OpenSSL() and DH_get_default_method() return pointers to the respective -B<DH_METHOD>s. - -DH_set_default_method() returns no value. - -DH_set_method() returns non-zero if the provided B<meth> was successfully set as -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)> if the allocation fails. Otherwise it -returns a pointer to the newly allocated structure. - -=head1 SEE ALSO - -L<dh(3)>, L<DH_new(3)>, L<DH_meth_new(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/doc/crypto/DH_size.pod b/doc/crypto/DH_size.pod deleted file mode 100644 index 8c1d151fcf..0000000000 --- a/doc/crypto/DH_size.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -DH_size, DH_bits - get Diffie-Hellman prime size - -=head1 SYNOPSIS - -#include <openssl/dh.h> - -int DH_size(const DH *dh); - -int DH_bits(const DH *dh); - -=head1 DESCRIPTION - -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(). - -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. - -=head1 SEE ALSO - -L<dh(3)>, L<DH_generate_key(3)>, -L<BN_num_bits(3)> - -=head1 HISTORY - -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/doc/crypto/DSA_SIG_new.pod b/doc/crypto/DSA_SIG_new.pod deleted file mode 100644 index 7503460a19..0000000000 --- a/doc/crypto/DSA_SIG_new.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -DSA_SIG_get0, DSA_SIG_set0, -DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - DSA_SIG *DSA_SIG_new(void); - 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 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)>. 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)>, L<ERR_get_error(3)>, -L<DSA_do_sign(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/doc/crypto/DSA_do_sign.pod b/doc/crypto/DSA_do_sign.pod deleted file mode 100644 index 5e56d20944..0000000000 --- a/doc/crypto/DSA_do_sign.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -DSA_do_sign, DSA_do_verify - raw DSA signature operations - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - 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); - -=head1 DESCRIPTION - -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)> may be used to precompute part -of the signing operation in case signature generation is -time-critical. - -DSA_do_verify() verifies that the signature B<sig> matches a given -message digest B<dgst> of size B<len>. B<dsa> is the signer's public -key. - -=head1 RETURN VALUES - -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)>. - -=head1 SEE ALSO - -L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, -L<DSA_SIG_new(3)>, -L<DSA_sign(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/doc/crypto/DSA_dup_DH.pod b/doc/crypto/DSA_dup_DH.pod deleted file mode 100644 index 6967ef3dcf..0000000000 --- a/doc/crypto/DSA_dup_DH.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -DSA_dup_DH - create a DH structure out of DSA structure - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - DH * DSA_dup_DH(const DSA *r); - -=head1 DESCRIPTION - -DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q -is lost during that conversion, but the resulting DH parameters -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)>. - -=head1 NOTE - -Be careful to avoid small subgroup attacks when using this. - -=head1 SEE ALSO - -L<dh(3)>, L<dsa(3)>, L<ERR_get_error(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/doc/crypto/DSA_generate_key.pod b/doc/crypto/DSA_generate_key.pod deleted file mode 100644 index 4781abed7a..0000000000 --- a/doc/crypto/DSA_generate_key.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -DSA_generate_key - generate DSA key pair - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - int DSA_generate_key(DSA *a); - -=head1 DESCRIPTION - -DSA_generate_key() expects B<a> to contain DSA parameters. It generates -a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>. - -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)>. - -=head1 SEE ALSO - -L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, -L<DSA_generate_parameters(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/doc/crypto/DSA_generate_parameters.pod b/doc/crypto/DSA_generate_parameters.pod deleted file mode 100644 index ca2c2ce7bb..0000000000 --- a/doc/crypto/DSA_generate_parameters.pod +++ /dev/null @@ -1,122 +0,0 @@ -=pod - -=head1 NAME - -DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters - -=head1 SYNOPSIS - - #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); - -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); - #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 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 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 -*B<h_ret>, unless these are B<NULL>. - -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)>. - -=over 4 - -=item * - -When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called -(m is 0 for the first candidate). - -=item * - -When a candidate for q has passed a test by trial division, -B<BN_GENCB_call(cb, 1, -1)> is called. -While a candidate for q is tested by Miller-Rabin primality tests, -B<BN_GENCB_call(cb, 1, i)> is called in the outer loop -(once for each witness that confirms that the candidate may be prime); -i is the loop counter (starting at 0). - -=item * - -When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and -B<BN_GENCB_call(cb, 3, 0)> are called. - -=item * - -Before a candidate for p (other than the first) is generated and tested, -B<BN_GENCB_call(cb, 0, counter)> is called. - -=item * - -When a candidate for p has passed the test by trial division, -B<BN_GENCB_call(cb, 1, -1)> is called. -While it is tested by the Miller-Rabin primality test, -B<BN_GENCB_call(cb, 1, i)> is called in the outer loop -(once for each witness that confirms that the candidate may be prime). -i is the loop counter (starting at 0). - -=item * - -When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called. - -=item * - -When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called. - -=back - -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)> for further information. - -=head1 RETURN VALUE - -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)>. - -=head1 BUGS - -Seed lengths E<gt> 20 are not supported. - -=head1 SEE ALSO - -L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, -L<DSA_free(3)>, L<BN_generate_prime(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/doc/crypto/DSA_get0_pqg.pod b/doc/crypto/DSA_get0_pqg.pod deleted file mode 100644 index e87e42a459..0000000000 --- a/doc/crypto/DSA_get0_pqg.pod +++ /dev/null @@ -1,102 +0,0 @@ -=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 version 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/doc/crypto/DSA_meth_new.pod b/doc/crypto/DSA_meth_new.pod deleted file mode 100644 index 68f744abc3..0000000000 --- a/doc/crypto/DSA_meth_new.pod +++ /dev/null @@ -1,193 +0,0 @@ -=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 version 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/doc/crypto/DSA_new.pod b/doc/crypto/DSA_new.pod deleted file mode 100644 index a967ab5da5..0000000000 --- a/doc/crypto/DSA_new.pod +++ /dev/null @@ -1,48 +0,0 @@ -=pod - -=head1 NAME - -DSA_new, DSA_free - allocate and free DSA objects - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - DSA* DSA_new(void); - - void DSA_free(DSA *dsa); - -=head1 DESCRIPTION - -DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to -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)>. Otherwise it returns a pointer -to the newly allocated structure. - -DSA_free() returns no value. - -=head1 SEE ALSO - -L<dsa(3)>, L<ERR_get_error(3)>, -L<DSA_generate_parameters(3)>, -L<DSA_generate_key(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/doc/crypto/DSA_set_method.pod b/doc/crypto/DSA_set_method.pod deleted file mode 100644 index a64725f7e4..0000000000 --- a/doc/crypto/DSA_set_method.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -DSA_set_default_method, DSA_get_default_method, -DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - 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); - - DSA_METHOD *DSA_OpenSSL(void); - -=head1 DESCRIPTION - -A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA -operations. By modifying the method, alternative implementations -such as hardware accelerators may be used. IMPORTANT: See the NOTES section for -important information about how these DSA API functions are affected by the use -of B<ENGINE> API calls. - -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 -been set as a default for DSA, so this function is no longer recommended. - -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 -recommended. - -DSA_set_method() selects B<meth> to perform all operations using the key -B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the -previous method was supplied by an ENGINE, the handle to that ENGINE will -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. 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 RETURN VALUES - -DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective -B<DSA_METHOD>s. - -DSA_set_default_method() returns no value. - -DSA_set_method() returns non-zero if the provided B<meth> was successfully set as -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)> if the allocation -fails. Otherwise it returns a pointer to the newly allocated structure. - -=head1 SEE ALSO - -L<dsa(3)>, L<DSA_new(3)>, L<DSA_meth_new(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/doc/crypto/DSA_sign.pod b/doc/crypto/DSA_sign.pod deleted file mode 100644 index ba0f6b863e..0000000000 --- a/doc/crypto/DSA_sign.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures - -=head1 SYNOPSIS - - #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_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); - -=head1 DESCRIPTION - -DSA_sign() computes a digital signature on the B<len> byte message -digest B<dgst> using the private key B<dsa> and places its ASN.1 DER -encoding at B<sigret>. The length of the signature is places in -*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory. - -DSA_sign_setup() may be used to precompute part of the signing -operation in case signature generation is time-critical. It expects -B<dsa> to contain DSA parameters. It places the precomputed values -in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing -the old ones unless *B<kinvp> and *B<rp> are NULL. These values may -be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>. -B<ctx> is a pre-allocated B<BN_CTX> or NULL. - -DSA_verify() verifies that the signature B<sigbuf> of size B<siglen> -matches a given message digest B<dgst> of size B<len>. -B<dsa> is the signer's public key. - -The B<type> parameter is ignored. - -The PRNG must be seeded before DSA_sign() (or DSA_sign_setup()) -is called. - -=head1 RETURN VALUES - -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)>. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, -L<DSA_do_sign(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/doc/crypto/DSA_size.pod b/doc/crypto/DSA_size.pod deleted file mode 100644 index 16e6f3a963..0000000000 --- a/doc/crypto/DSA_size.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -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 - -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 - -DSA_size() returns the size in bytes. - -DSA_bits() returns the number of bits in the key. - -=head1 SEE ALSO - -L<dsa(3)>, L<DSA_sign(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/doc/crypto/ECDSA_SIG_new.pod b/doc/crypto/ECDSA_SIG_new.pod deleted file mode 100644 index f6aaed192b..0000000000 --- a/doc/crypto/ECDSA_SIG_new.pod +++ /dev/null @@ -1,207 +0,0 @@ -=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 it's 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 signatures is stored in B<sig> and it's -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(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/doc/crypto/ECPKParameters_print.pod b/doc/crypto/ECPKParameters_print.pod deleted file mode 100644 index c9c362835e..0000000000 --- a/doc/crypto/ECPKParameters_print.pod +++ /dev/null @@ -1,44 +0,0 @@ -=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(3)>, L<ec(3)>, 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-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/doc/crypto/EC_GFp_simple_method.pod b/doc/crypto/EC_GFp_simple_method.pod deleted file mode 100644 index 89c590eb2a..0000000000 --- a/doc/crypto/EC_GFp_simple_method.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=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 EC_METHOD objects - -=head1 SYNOPSIS - - #include <openssl/ec.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); - - int EC_METHOD_get_field_type(const EC_METHOD *meth); - -=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)>) 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. - -For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method. - -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)>). 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)>). - -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 -implementations are not available on all platforms. - -EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either -F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is -F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the -obj_mac.h header file. - -=head1 RETURN VALUES - -All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure. - -EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports. - -=head1 SEE ALSO - -L<crypto(3)>, L<ec(3)>, 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-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/doc/crypto/EC_GROUP_copy.pod b/doc/crypto/EC_GROUP_copy.pod deleted file mode 100644 index 6b398dfefc..0000000000 --- a/doc/crypto/EC_GROUP_copy.pod +++ /dev/null @@ -1,206 +0,0 @@ -=pod - -=head1 NAME - -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> - - 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_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); - 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); - - 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_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); - - 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); - -=head1 DESCRIPTION - -EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD. - -EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created -EC_GROUP object. - -EC_GROUP_method_of obtains the EC_METHOD of B<group>. - -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> 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>. - -The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters -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)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name -will return 0. - -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 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_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. - -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. - -The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form -for the curve respectively. - -ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages -in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. -If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library -does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block -containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the -builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using -EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use -this seed value, although it will be preserved in any ASN1 based communications. - -EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be -the value m. - -The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid. -For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is -simply b. In either case for the curve to be valid the discriminant must be non zero. - -The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include -verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has -the correct order. - -EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not. - -The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves -defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial -function f(x). This function is either a trinomial of the form: - -f(x) = x^m + x^k + 1 with m > k >= 1 - -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>. 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. - -=head1 RETURN VALUES - -The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check, -EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis. - -EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error. - -EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error. - -EC_GROUP_get0_generator returns the generator for the given curve or NULL on error. - -EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form -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. - -EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is -0, the return value will be 1. On error 0 is returned. - -EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error. - -EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a -trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. - -=head1 SEE ALSO - -L<crypto(3)>, L<ec(3)>, 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-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/doc/crypto/EC_GROUP_new.pod b/doc/crypto/EC_GROUP_new.pod deleted file mode 100644 index 25129100b6..0000000000 --- a/doc/crypto/EC_GROUP_new.pod +++ /dev/null @@ -1,120 +0,0 @@ -=pod - -=head1 NAME - -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> - - 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); - - 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); - - 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); - - 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 - -Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the -prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised -elliptic curve equation as follows: - -y^2 mod p = x^3 +ax + b mod p - -The second form is those defined over a binary field F2^m where the elements of the field are integers of length at -most m bits. For this form the elliptic curve equation is modified to: - -y^2 + xy = x^3 + ax^2 + b (where b != 0) - -Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL -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)>). 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 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 -appropriate EC_group_set_curve function. An appropriate default implementation method will be used. - -Whilst the library can be used to create any curve using the functions described above, there are also a number of -predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function -EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function -will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of -curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be -provided. The return value is the total number of curves available (whether that number has been populated in B<r> or -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; - -Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve. - -In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to -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 - -All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. - -EC_get_builtin_curves returns the number of builtin curves that are available. - -EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error. - -=head1 SEE ALSO - -L<crypto(3)>, L<ec(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)>, L<d2i_ECPKParameters(3)> - -=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/doc/crypto/EC_KEY_get_enc_flags.pod b/doc/crypto/EC_KEY_get_enc_flags.pod deleted file mode 100644 index abc55c148f..0000000000 --- a/doc/crypto/EC_KEY_get_enc_flags.pod +++ /dev/null @@ -1,59 +0,0 @@ -=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(3)>, L<ec(3)>, 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-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/doc/crypto/EC_KEY_new.pod b/doc/crypto/EC_KEY_new.pod deleted file mode 100644 index 83a2c6d097..0000000000 --- a/doc/crypto/EC_KEY_new.pod +++ /dev/null @@ -1,183 +0,0 @@ -=pod - -=head1 NAME - -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> - - 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); - 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_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); - 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); - - 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); - - 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); - - size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf); - -=head1 DESCRIPTION - -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. - -=head1 RETURN VALUES - -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_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. - -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_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. - -EC_KEY_get_conv_form() return the point_conversion_form for the EC_KEY. - -EC_KEY_key2buf(), EC_KEY_priv2oct() and EC_KEY_priv2buf() return the length -of the buffer or 0 on error. - -=head1 SEE ALSO - -L<crypto(3)>, L<ec(3)>, 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 - -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/doc/crypto/EC_POINT_add.pod b/doc/crypto/EC_POINT_add.pod deleted file mode 100644 index c029de42b1..0000000000 --- a/doc/crypto/EC_POINT_add.pod +++ /dev/null @@ -1,80 +0,0 @@ -=pod - -=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 EC_POINT objects - -=head1 SYNOPSIS - - #include <openssl/ec.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); - 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); - - -=head1 DESCRIPTION - -EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the -result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>. - -EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>. - -The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not. - -EC_POINT_is_on_curve tests whether the supplied point is on the curve or not. - -EC_POINT_cmp compares the two supplied points and tests whether or not they are equal. - -The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine -co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be -forced. - -EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>. - -EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value -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)> for information -about the generator. - - -=head1 RETURN VALUES - -The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, -EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult. - -EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise. - -EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error. - -EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error. - -EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not. - -=head1 SEE ALSO - -L<crypto(3)>, L<ec(3)>, 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-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/doc/crypto/EC_POINT_new.pod b/doc/crypto/EC_POINT_new.pod deleted file mode 100644 index 206648c83b..0000000000 --- a/doc/crypto/EC_POINT_new.pod +++ /dev/null @@ -1,196 +0,0 @@ -=pod - -=head1 NAME - -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> - - 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); - 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 *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 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. - -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() and EC_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_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_hex2point() returns the pointer to the EC_POINT supplied, or NULL on -error. - -=head1 SEE ALSO - -L<crypto(3)>, L<ec(3)>, 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-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/doc/crypto/ENGINE_add.pod b/doc/crypto/ENGINE_add.pod deleted file mode 100644 index 37384f69b5..0000000000 --- a/doc/crypto/ENGINE_add.pod +++ /dev/null @@ -1,611 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/engine.h> - - ENGINE *ENGINE_get_first(void); - ENGINE *ENGINE_get_last(void); - ENGINE *ENGINE_get_next(ENGINE *e); - ENGINE *ENGINE_get_prev(ENGINE *e); - - int ENGINE_add(ENGINE *e); - int ENGINE_remove(ENGINE *e); - - ENGINE *ENGINE_by_id(const char *id); - - int ENGINE_init(ENGINE *e); - int ENGINE_finish(ENGINE *e); - - void ENGINE_load_builtin_engines(void); - - ENGINE *ENGINE_get_default_RSA(void); - ENGINE *ENGINE_get_default_DSA(void); - ENGINE *ENGINE_get_default_ECDH(void); - ENGINE *ENGINE_get_default_ECDSA(void); - ENGINE *ENGINE_get_default_DH(void); - ENGINE *ENGINE_get_default_RAND(void); - ENGINE *ENGINE_get_cipher_engine(int nid); - ENGINE *ENGINE_get_digest_engine(int nid); - - int ENGINE_set_default_RSA(ENGINE *e); - int ENGINE_set_default_DSA(ENGINE *e); - int ENGINE_set_default_ECDH(ENGINE *e); - int ENGINE_set_default_ECDSA(ENGINE *e); - int ENGINE_set_default_DH(ENGINE *e); - int ENGINE_set_default_RAND(ENGINE *e); - int ENGINE_set_default_ciphers(ENGINE *e); - int ENGINE_set_default_digests(ENGINE *e); - int ENGINE_set_default_string(ENGINE *e, const char *list); - - int ENGINE_set_default(ENGINE *e, unsigned int flags); - - unsigned int ENGINE_get_table_flags(void); - void ENGINE_set_table_flags(unsigned int flags); - - int ENGINE_register_RSA(ENGINE *e); - void ENGINE_unregister_RSA(ENGINE *e); - void ENGINE_register_all_RSA(void); - int ENGINE_register_DSA(ENGINE *e); - void ENGINE_unregister_DSA(ENGINE *e); - void ENGINE_register_all_DSA(void); - int ENGINE_register_ECDH(ENGINE *e); - void ENGINE_unregister_ECDH(ENGINE *e); - void ENGINE_register_all_ECDH(void); - int ENGINE_register_ECDSA(ENGINE *e); - void ENGINE_unregister_ECDSA(ENGINE *e); - void ENGINE_register_all_ECDSA(void); - int ENGINE_register_DH(ENGINE *e); - void ENGINE_unregister_DH(ENGINE *e); - void ENGINE_register_all_DH(void); - int ENGINE_register_RAND(ENGINE *e); - void ENGINE_unregister_RAND(ENGINE *e); - void ENGINE_register_all_RAND(void); - int ENGINE_register_ciphers(ENGINE *e); - void ENGINE_unregister_ciphers(ENGINE *e); - void ENGINE_register_all_ciphers(void); - int ENGINE_register_digests(ENGINE *e); - void ENGINE_unregister_digests(ENGINE *e); - void ENGINE_register_all_digests(void); - int ENGINE_register_complete(ENGINE *e); - int ENGINE_register_all_complete(void); - - int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); - int ENGINE_cmd_is_executable(ENGINE *e, int cmd); - int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, - long i, void *p, void (*f)(void), int cmd_optional); - int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, - int cmd_optional); - - ENGINE *ENGINE_new(void); - int ENGINE_free(ENGINE *e); - int ENGINE_up_ref(ENGINE *e); - - int ENGINE_set_id(ENGINE *e, const char *id); - int ENGINE_set_name(ENGINE *e, const char *name); - int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); - int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); - int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); - 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_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); - int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); - int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); - int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); - int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); - int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); - int ENGINE_set_flags(ENGINE *e, int flags); - int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); - - const char *ENGINE_get_id(const ENGINE *e); - const char *ENGINE_get_name(const ENGINE *e); - const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); - const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); - const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); - 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); - 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); - ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); - ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); - ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); - ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); - ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); - const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); - const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); - int ENGINE_get_flags(const ENGINE *e); - const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); - - EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, - UI_METHOD *ui_method, void *callback_data); - EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, - UI_METHOD *ui_method, void *callback_data); - -Deprecated: - - #if OPENSSL_API_COMPAT < 0x10100000L - void ENGINE_cleanup(void) - #endif - -=head1 DESCRIPTION - -These functions create, manipulate, and use cryptographic modules in the -form of B<ENGINE> objects. These objects act as containers for -implementations of cryptographic algorithms, and support a -reference-counted mechanism to allow them to be dynamically loaded in and -out of the running application. - -The cryptographic functionality that can be provided by an B<ENGINE> -implementation includes the following abstractions; - - RSA_METHOD - for providing alternative RSA implementations - DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, - - 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 - -=head2 Reference counting and handles - -Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be -treated as handles - ie. not only as pointers, but also as references to -the underlying ENGINE object. Ie. one should obtain a new reference when -making copies of an ENGINE pointer if the copies will be used (and -released) independently. - -ENGINE objects have two levels of reference-counting to match the way in -which the objects are used. At the most basic level, each ENGINE pointer is -inherently a B<structural> reference - a structural reference is required -to use the pointer value at all, as this kind of reference is a guarantee -that the structure can not be deallocated until the reference is released. - -However, a structural reference provides no guarantee that the ENGINE is -initialised and able to use any of its cryptographic -implementations. Indeed it's quite possible that most ENGINEs will not -initialise at all in typical environments, as ENGINEs are typically used to -support specialised hardware. To use an ENGINE's functionality, you need a -B<functional> reference. This kind of reference can be considered a -specialised form of structural reference, because each functional reference -implicitly contains a structural reference as well - however to avoid -difficult-to-find programming bugs, it is recommended to treat the two -kinds of reference independently. If you have a functional reference to an -ENGINE, you have a guarantee that the ENGINE has been initialised and -is ready to perform cryptographic operations, and will remain initialised -until after you have released your reference. - -I<Structural references> - -This basic type of reference is used for instantiating new ENGINEs, -iterating across OpenSSL's internal linked-list of loaded -ENGINEs, reading information about an ENGINE, etc. Essentially a structural -reference is sufficient if you only need to query or manipulate the data of -an ENGINE implementation rather than use its functionality. - -The ENGINE_new() function returns a structural reference to a new (empty) -ENGINE object. There are other ENGINE API functions that return structural -references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), -ENGINE_get_next(), ENGINE_get_prev(). All structural references should be -released by a corresponding to call to the ENGINE_free() function - the -ENGINE object itself will only actually be cleaned up and deallocated when -the last structural reference is released. - -It should also be noted that many ENGINE API function calls that accept a -structural reference will internally obtain another reference - typically -this happens whenever the supplied ENGINE will be needed by OpenSSL after -the function has returned. Eg. the function to add a new ENGINE to -OpenSSL's internal list is ENGINE_add() - if this function returns success, -then OpenSSL will have stored a new structural reference internally so the -caller is still responsible for freeing their own reference with -ENGINE_free() when they are finished with it. In a similar way, some -functions will automatically release the structural reference passed to it -if part of the function's job is to do so. Eg. the ENGINE_get_next() and -ENGINE_get_prev() functions are used for iterating across the internal -ENGINE list - they will return a new structural reference to the next (or -previous) ENGINE in the list or NULL if at the end (or beginning) of the -list, but in either case the structural reference passed to the function is -released on behalf of the caller. - -To clarify a particular function's handling of references, one should -always consult that function's documentation "man" page, or failing that -the openssl/engine.h header file includes some hints. - -I<Functional references> - -As mentioned, functional references exist when the cryptographic -functionality of an ENGINE is required to be available. A functional -reference can be obtained in one of two ways; from an existing structural -reference to the required ENGINE, or by asking OpenSSL for the default -operational ENGINE for a given cryptographic purpose. - -To obtain a functional reference from an existing structural reference, -call the ENGINE_init() function. This returns zero if the ENGINE was not -already operational and couldn't be successfully initialised (eg. lack of -system drivers, no special hardware attached, etc), otherwise it will -return non-zero to indicate that the ENGINE is now operational and will -have allocated a new B<functional> reference to the ENGINE. All functional -references are released by calling ENGINE_finish() (which removes the -implicit structural reference as well). - -The second way to get a functional reference is by asking OpenSSL for a -default implementation for a given task, eg. by ENGINE_get_default_RSA(), -ENGINE_get_default_cipher_engine(), etc. These are discussed in the next -section, though they are not usually required by application programmers as -they are used automatically when creating and using the relevant -algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. - -=head2 Default implementations - -For each supported abstraction, the ENGINE code maintains an internal table -of state to control which implementations are available for a given -abstraction and which should be used by default. These implementations are -registered in the tables and indexed by an 'nid' value, because -abstractions like EVP_CIPHER and EVP_DIGEST support many distinct -algorithms and modes, and ENGINEs can support arbitrarily many of them. -In the case of other abstractions like RSA, DSA, etc, there is only one -"algorithm" so all implementations implicitly register using the same 'nid' -index. - -When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg. -when calling RSA_new_method(NULL)), a "get_default" call will be made to the -ENGINE subsystem to process the corresponding state table and return a -functional reference to an initialised ENGINE whose implementation should be -used. If no ENGINE should (or can) be used, it will return NULL and the caller -will operate with a NULL ENGINE handle - this usually equates to using the -conventional software implementation. In the latter case, OpenSSL will from -then on behave the way it used to before the ENGINE API existed. - -Each state table has a flag to note whether it has processed this -"get_default" query since the table was last modified, because to process -this question it must iterate across all the registered ENGINEs in the -table trying to initialise each of them in turn, in case one of them is -operational. If it returns a functional reference to an ENGINE, it will -also cache another reference to speed up processing future queries (without -needing to iterate across the table). Likewise, it will cache a NULL -response if no ENGINE was available so that future queries won't repeat the -same iteration unless the state table changes. This behaviour can also be -changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using -ENGINE_set_table_flags()), no attempted initialisations will take place, -instead the only way for the state table to return a non-NULL ENGINE to the -"get_default" query will be if one is expressly set in the table. Eg. -ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except -that it also sets the state table's cached response for the "get_default" -query. In the case of abstractions like EVP_CIPHER, where implementations are -indexed by 'nid', these flags and cached-responses are distinct for each 'nid' -value. - -=head2 Application requirements - -This section will explain the basic things an application programmer should -support to make the most useful elements of the ENGINE functionality -available to the user. The first thing to consider is whether the -programmer wishes to make alternative ENGINE modules available to the -application and user. OpenSSL maintains an internal linked list of -"visible" ENGINEs from which it has to operate - at start-up, this list is -empty and in fact if an application does not call any ENGINE API calls and -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. - -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) - -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, 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 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. 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 -"registered" or called into use by OpenSSL automatically - that behaviour -is something for the application to control. Some applications -will want to allow the user to specify exactly which ENGINE they want used -if any is to be used at all. Others may prefer to load all support and have -OpenSSL automatically use at run-time any ENGINE that is able to -successfully initialise - ie. to assume that this corresponds to -acceleration hardware attached to the machine or some such thing. There are -probably numerous other ways in which applications may prefer to handle -things, so we will simply illustrate the consequences as they apply to a -couple of simple cases and leave developers to consider these and the -source code to openssl's builtin utilities as guides. - -I<Using a specific ENGINE implementation> - -Here we'll assume an application has been configured by its user or admin -to want to use the "ACME" ENGINE if it is available in the version of -OpenSSL the application was compiled with. If it is available, it should be -used by default for all RSA, DSA, and symmetric cipher operations, otherwise -OpenSSL should use its builtin software as per usual. The following code -illustrates how to approach this; - - ENGINE *e; - const char *engine_id = "ACME"; - ENGINE_load_builtin_engines(); - e = ENGINE_by_id(engine_id); - if(!e) - /* the engine isn't available */ - return; - if(!ENGINE_init(e)) { - /* the engine couldn't initialise, release 'e' */ - ENGINE_free(e); - return; - } - if(!ENGINE_set_default_RSA(e)) - /* This should only happen when 'e' can't initialise, but the previous - * statement suggests it did. */ - abort(); - ENGINE_set_default_DSA(e); - ENGINE_set_default_ciphers(e); - /* Release the functional reference from ENGINE_init() */ - ENGINE_finish(e); - /* Release the structural reference from ENGINE_by_id() */ - ENGINE_free(e); - -I<Automatically using builtin ENGINE implementations> - -Here we'll assume we want to load and register all ENGINE implementations -bundled with OpenSSL, such that for any cryptographic algorithm required by -OpenSSL - if there is an ENGINE that implements it and can be initialised, -it should be used. The following code illustrates how this can work; - - /* Load all bundled ENGINEs into memory and make them visible */ - ENGINE_load_builtin_engines(); - /* Register all of them for every algorithm they collectively implement */ - ENGINE_register_all_complete(); - -That's all that's required. Eg. the next time OpenSSL tries to set up an -RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to -ENGINE_init() and if any of those succeed, that ENGINE will be set as the -default for RSA use from then on. - -=head2 Advanced configuration support - -There is a mechanism supported by the ENGINE framework that allows each -ENGINE implementation to define an arbitrary set of configuration -"commands" and expose them to OpenSSL and any applications based on -OpenSSL. This mechanism is entirely based on the use of name-value pairs -and assumes ASCII input (no unicode or UTF for now!), so it is ideal if -applications want to provide a transparent way for users to provide -arbitrary configuration "directives" directly to such ENGINEs. It is also -possible for the application to dynamically interrogate the loaded ENGINE -implementations for the names, descriptions, and input flags of their -available "control commands", providing a more flexible configuration -scheme. However, if the user is expected to know which ENGINE device he/she -is using (in the case of specialised hardware, this goes without saying) -then applications may not need to concern themselves with discovering the -supported control commands and simply prefer to pass settings into ENGINEs -exactly as they are provided by the user. - -Before illustrating how control commands work, it is worth mentioning what -they are typically used for. Broadly speaking there are two uses for -control commands; the first is to provide the necessary details to the -implementation (which may know nothing at all specific to the host system) -so that it can be initialised for use. This could include the path to any -driver or config files it needs to load, required network addresses, -smart-card identifiers, passwords to initialise protected devices, -logging information, etc etc. This class of commands typically needs to be -passed to an ENGINE B<before> attempting to initialise it, ie. before -calling ENGINE_init(). The other class of commands consist of settings or -operations that tweak certain behaviour or cause certain operations to take -place, and these commands may work either before or after ENGINE_init(), or -in some cases both. ENGINE implementations should provide indications of -this in the descriptions attached to builtin control commands and/or in -external product documentation. - -I<Issuing control commands to an ENGINE> - -Let's illustrate by example; a function for which the caller supplies the -name of the ENGINE it wishes to use, a table of string-pairs for use before -initialisation, and another table for use after initialisation. Note that -the string-pairs used for control commands consist of a command "name" -followed by the command "parameter" - the parameter could be NULL in some -cases but the name can not. This function should initialise the ENGINE -(issuing the "pre" commands beforehand and the "post" commands afterwards) -and set it as the default for everything except RAND and then return a -boolean success or failure. - - int generic_load_engine_fn(const char *engine_id, - const char **pre_cmds, int pre_num, - const char **post_cmds, int post_num) - { - ENGINE *e = ENGINE_by_id(engine_id); - 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; - } - if (!ENGINE_init(e)) { - fprintf(stderr, "Failed initialisation\n"); - ENGINE_free(e); - return 0; - } - /* ENGINE_init() returned a functional reference, so free the structural - * reference from ENGINE_by_id(). */ - ENGINE_free(e); - while(post_num--) { - if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { - fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, - post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); - ENGINE_finish(e); - return 0; - } - post_cmds += 2; - } - ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); - /* Success */ - return 1; - } - -Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can -relax the semantics of the function - if set non-zero it will only return -failure if the ENGINE supported the given command name but failed while -executing it, if the ENGINE doesn't support the command name it will simply -return success without doing anything. In this case we assume the user is -only supplying commands specific to the given ENGINE so we set this to -FALSE. - -I<Discovering supported control commands> - -It is possible to discover at run-time the names, numerical-ids, descriptions -and input parameters of the control commands supported by an ENGINE using a -structural reference. Note that some control commands are defined by OpenSSL -itself and it will intercept and handle these control commands on behalf of the -ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command. -openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands -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 control -commands implemented by a given ENGINE, specifically the commands: - - 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 -queries. An ENGINE has 3 properties it exposes that can affect how this behaves; -it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in -the ENGINE's flags, and it can expose an array of control command descriptions. -If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will -simply pass all these "core" control commands directly to the ENGINE's ctrl() -handler (and thus, it must have supplied one), so it is up to the ENGINE to -reply to these "discovery" commands itself. If that flag is not set, then the -OpenSSL framework code will work with the following rules; - - if no ctrl() handler supplied; - ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), - all other commands fail. - if a ctrl() handler was supplied but no array of control commands; - ENGINE_HAS_CTRL_FUNCTION returns TRUE, - all other commands fail. - if a ctrl() handler and array of control commands was supplied; - ENGINE_HAS_CTRL_FUNCTION returns TRUE, - all other commands proceed processing ... - -If the ENGINE's array of control commands is empty then all other commands will -fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of -the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the -identifier of a command supported by the ENGINE and returns the next command -identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string -name for a command and returns the corresponding identifier or fails if no such -command name exists, and the remaining commands take a command identifier and -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: - - 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 -for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). -"INTERNAL" commands are not intended to be exposed to text-based configuration -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 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). - -=head1 SEE ALSO - -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-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/doc/crypto/ERR_GET_LIB.pod b/doc/crypto/ERR_GET_LIB.pod deleted file mode 100644 index 10e250f445..0000000000 --- a/doc/crypto/ERR_GET_LIB.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and -reason code - -=head1 SYNOPSIS - - #include <openssl/err.h> - - int ERR_GET_LIB(unsigned long e); - - int ERR_GET_FUNC(unsigned long e); - - int ERR_GET_REASON(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. - -The library number and function code describe where the error -occurred, the reason code is the information about what went wrong. - -Each sub-library of OpenSSL has a unique library number; function and -reason codes are unique within each sub-library. Note that different -libraries may use the same value to signal different functions and -reasons. - -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. - -=head1 RETURN VALUES - -The library number, function code and reason code respectively. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_get_error(3)> - -=head1 HISTORY - -ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in -all versions of OpenSSL. - -=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/doc/crypto/ERR_clear_error.pod b/doc/crypto/ERR_clear_error.pod deleted file mode 100644 index 892c67fcf9..0000000000 --- a/doc/crypto/ERR_clear_error.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -ERR_clear_error - clear the error queue - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_clear_error(void); - -=head1 DESCRIPTION - -ERR_clear_error() empties the current thread's error queue. - -=head1 RETURN VALUES - -ERR_clear_error() has no return value. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_get_error(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/doc/crypto/ERR_error_string.pod b/doc/crypto/ERR_error_string.pod deleted file mode 100644 index 12f4f72be5..0000000000 --- a/doc/crypto/ERR_error_string.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -ERR_error_string, ERR_error_string_n, ERR_lib_error_string, -ERR_func_error_string, ERR_reason_error_string - obtain human-readable -error message - -=head1 SYNOPSIS - - #include <openssl/err.h> - - char *ERR_error_string(unsigned long e, char *buf); - void ERR_error_string_n(unsigned long e, char *buf, size_t len); - - 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); - -=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 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. -For ERR_error_string_n(), I<buf> may not be B<NULL>. - -The string will have the following format: - - error:[error code]:[library name]:[function name]:[reason string] - -I<error code> is an 8 digit hexadecimal number, I<library name>, -I<function name> and I<reason string> are ASCII text. - -ERR_lib_error_string(), ERR_func_error_string() and -ERR_reason_error_string() return the library name, function -name and reason string respectively. - -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)> can be used to print -all error codes currently in the queue. - -=head1 RETURN VALUES - -ERR_error_string() returns a pointer to a static buffer containing the -string if I<buf> B<== NULL>, I<buf> otherwise. - -ERR_lib_error_string(), ERR_func_error_string() and -ERR_reason_error_string() return the strings, and B<NULL> if -none is registered for the error code. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_get_error(3)>, -L<ERR_print_errors(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/doc/crypto/ERR_get_error.pod b/doc/crypto/ERR_get_error.pod deleted file mode 100644 index a7efc74d6a..0000000000 --- a/doc/crypto/ERR_get_error.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -ERR_get_error, ERR_peek_error, ERR_peek_last_error, -ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, -ERR_get_error_line_data, ERR_peek_error_line_data, -ERR_peek_last_error_line_data - obtain error code and data - -=head1 SYNOPSIS - - #include <openssl/err.h> - - unsigned long ERR_get_error(void); - unsigned long ERR_peek_error(void); - unsigned long ERR_peek_last_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_peek_last_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); - unsigned long ERR_peek_last_error_line_data(const char **file, int *line, - const char **data, int *flags); - -=head1 DESCRIPTION - -ERR_get_error() returns the earliest error code from the thread's error -queue and removes the entry. This function can be called repeatedly -until there are no more error codes to return. - -ERR_peek_error() returns the earliest error code from the thread's -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)> for obtaining information about -location and reason of the error, and -L<ERR_error_string(3)> for human-readable error -messages. - -ERR_get_error_line(), ERR_peek_error_line() and -ERR_peek_last_error_line() are the same as the above, but they -additionally store the file name and line number where -the error occurred in *B<file> and *B<line>, unless these are B<NULL>. - -ERR_get_error_line_data(), ERR_peek_error_line_data() and -ERR_peek_last_error_line_data() store additional data and flags -associated with the error code in *B<data> -and *B<flags>, unless these are B<NULL>. *B<data> contains a string -if *B<flags>&B<ERR_TXT_STRING> is true. - -An application B<MUST NOT> free the *B<data> pointer (or any other pointers -returned by these functions) with OPENSSL_free() as freeing is handled -automatically by the error library. - -=head1 RETURN VALUES - -The error code, or 0 if there is no error in the queue. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_error_string(3)>, -L<ERR_GET_LIB(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/doc/crypto/ERR_load_crypto_strings.pod b/doc/crypto/ERR_load_crypto_strings.pod deleted file mode 100644 index 15f8000c4e..0000000000 --- a/doc/crypto/ERR_load_crypto_strings.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - -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. - -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 - -ERR_load_crypto_strings(), SSL_load_error_strings() and -ERR_free_strings() return no values. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_error_string(3)> - -=head1 HISTORY - -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-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/doc/crypto/ERR_load_strings.pod b/doc/crypto/ERR_load_strings.pod deleted file mode 100644 index 86ee5fda24..0000000000 --- a/doc/crypto/ERR_load_strings.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load -arbitrary error strings - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_load_strings(int lib, ERR_STRING_DATA str[]); - - int ERR_get_next_error_library(void); - - unsigned long ERR_PACK(int lib, int func, int reason); - -=head1 DESCRIPTION - -ERR_load_strings() registers error strings for library number B<lib>. - -B<str> is an array of error string data: - - typedef struct ERR_string_data_st - { - unsigned long error; - char *string; - } ERR_STRING_DATA; - -The error code is generated from the library number and a function and -reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>). -ERR_PACK() is a macro. - -The last entry in the array is {0,0}. - -ERR_get_next_error_library() can be used to assign library numbers -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 zero on failure, otherwise a new -library number. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_load_strings(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/doc/crypto/ERR_print_errors.pod b/doc/crypto/ERR_print_errors.pod deleted file mode 100644 index 17229af30c..0000000000 --- a/doc/crypto/ERR_print_errors.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb -- print error messages - -=head1 SYNOPSIS - - #include <openssl/err.h> - - 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 - -ERR_print_errors() is a convenience function that prints the error -strings for all errors that OpenSSL has recorded to B<bp>, thus -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: - - [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message] - -I<error code> is an 8 digit hexadecimal number. I<library name>, -I<function name> and I<reason string> are ASCII text, as is I<optional -text message> if one was set for the respective error code. - -If there is no text string registered for the given error code, -the error string will contain the numeric code. - -=head1 RETURN VALUES - -ERR_print_errors() and ERR_print_errors_fp() return no values. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_error_string(3)>, -L<ERR_get_error(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/doc/crypto/ERR_put_error.pod b/doc/crypto/ERR_put_error.pod deleted file mode 100644 index 9d2405e3d3..0000000000 --- a/doc/crypto/ERR_put_error.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -ERR_put_error, ERR_add_error_data - record an error - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_put_error(int lib, int func, int reason, const char *file, - int line); - - void ERR_add_error_data(int num, ...); - void ERR_add_error_data(int num, va_list arg); - -=head1 DESCRIPTION - -ERR_put_error() adds an error code to the thread's error queue. It -signals that the error of reason code B<reason> occurred in function -B<func> of library B<lib>, in line number B<line> of B<file>. -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)> 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 -no values. - -=head1 SEE ALSO - -L<err(3)>, L<ERR_load_strings(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/doc/crypto/ERR_remove_state.pod b/doc/crypto/ERR_remove_state.pod deleted file mode 100644 index f2e71e3948..0000000000 --- a/doc/crypto/ERR_remove_state.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -ERR_remove_thread_state, ERR_remove_state - DEPRECATED - -=head1 SYNOPSIS - -Deprecated: - - #if OPENSSL_API_COMPAT < 0x10000000L - void ERR_remove_state(unsigned long pid); - #endif - - #if OPENSSL_API_COMPAT < 0x10100000L - void ERR_remove_thread_state(void *); - #endif - -=head1 DESCRIPTION - -The functions described here were used to free the error queue -associated with the current or specified thread. - -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 - -The functions described here return no value. - -=head1 SEE ALSO - -L<err(3)>, L<OPENSSL_init_crypto(3)> - -=head1 HISTORY - -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-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/doc/crypto/ERR_set_mark.pod b/doc/crypto/ERR_set_mark.pod deleted file mode 100644 index 9c55f5a7bb..0000000000 --- a/doc/crypto/ERR_set_mark.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark - -=head1 SYNOPSIS - - #include <openssl/err.h> - - int ERR_set_mark(void); - - int ERR_pop_to_mark(void); - -=head1 DESCRIPTION - -ERR_set_mark() sets a mark on the current topmost error record if there -is one. - -ERR_pop_to_mark() will pop the top of the error stack until a mark is found. -The mark is then removed. If there is no mark, the whole stack is removed. - -=head1 RETURN VALUES - -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 - -L<err(3)> - -=head1 COPYRIGHT - -Copyright 2003-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/doc/crypto/EVP_BytesToKey.pod b/doc/crypto/EVP_BytesToKey.pod deleted file mode 100644 index 728c94e980..0000000000 --- a/doc/crypto/EVP_BytesToKey.pod +++ /dev/null @@ -1,78 +0,0 @@ -=pod - -=head1 NAME - -EVP_BytesToKey - password based encryption routine - -=head1 SYNOPSIS - - #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); - -=head1 DESCRIPTION - -EVP_BytesToKey() derives a key and IV from various parameters. B<type> is -the cipher to derive the key and IV for. B<md> is the message digest to use. -The B<salt> parameter is used as a salt in the derivation: it should point to -an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing -B<datal> bytes which is used to derive the keying data. B<count> is the -iteration count to use. The derived key and IV will be written to B<key> -and B<iv> respectively. - -=head1 NOTES - -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 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 -B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 -otherwise a non standard extension is used to derive the extra data. - -Newer applications should use a more modern algorithm such as PBKDF2 as -defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC. - -=head1 KEY DERIVATION ALGORITHM - -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) - -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. - -The initial bytes are used for the key and the subsequent bytes for -the IV. - -=head1 RETURN VALUES - -If B<data> is NULL, then EVP_BytesToKey() returns the number of bytes -needed to store the derived key. -Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes, -or 0 on error. - -=head1 SEE ALSO - -L<evp(3)>, L<rand(3)>, -L<PKCS5_PBKDF2_HMAC(3)>, -L<EVP_EncryptInit(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/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod b/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod deleted file mode 100644 index 3a57fcdb67..0000000000 --- a/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod +++ /dev/null @@ -1,51 +0,0 @@ -=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/doc/crypto/EVP_CIPHER_meth_new.pod b/doc/crypto/EVP_CIPHER_meth_new.pod deleted file mode 100644 index 6e18ed5412..0000000000 --- a/doc/crypto/EVP_CIPHER_meth_new.pod +++ /dev/null @@ -1,238 +0,0 @@ -=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 - -=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_ctrl() sets the control function for B<cipher>. - -=head1 RETURN VALUES - -EVP_CIPHER_meth_get_input_blocksize(), EVP_CIPHER_meth_get_result_size(), -EVP_CIPHER_meth_get_app_datasize(), EVP_CIPHER_meth_get_flags(), -EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_update(), -EVP_CIPHER_meth_get_final(), EVP_CIPHER_meth_get_copy(), -EVP_CIPHER_meth_get_cleanup() and EVP_CIPHER_meth_get_ctrl() are all used -to retrieve the method data given with the EVP_CIPHER_meth_set_*() -functions above. - -=head1 SEE ALSO - -L<EVP_EncryptInit> - -=head1 HISTORY - -The B<EVP_CIPHER> structure was openly available in OpenSSL before version -1.1. -The functions described here were added in OpenSSL version 1.1. - -=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/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod deleted file mode 100644 index d615b31b87..0000000000 --- a/doc/crypto/EVP_DigestInit.pod +++ /dev/null @@ -1,259 +0,0 @@ -=pod - -=head1 NAME - -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_sha1, -EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_mdc2, -EVP_ripemd160, EVP_blake2b_512, EVP_blake2s_256, EVP_get_digestbyname, -EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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_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); - - int EVP_MD_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); - 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_sha1(void); - const EVP_MD *EVP_mdc2(void); - const EVP_MD *EVP_ripemd160(void); - const EVP_MD *EVP_blake2b_512(void); - const EVP_MD *EVP_blake2s_256(void); - - const EVP_MD *EVP_sha224(void); - const EVP_MD *EVP_sha256(void); - const EVP_MD *EVP_sha384(void); - const EVP_MD *EVP_sha512(void); - - const EVP_MD *EVP_get_digestbyname(const char *name); - 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, -and should be used instead of the cipher-specific functions. - -EVP_MD_CTX_new() 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 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 -digest context B<ctx>. This function can be called several times on the -same B<ctx> to hash additional data. - -EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places -it in B<md>. If the B<s> parameter is not NULL then the number of -bytes of data written (i.e. the length of the digest) will be written -to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. -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_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 -before calling this function. - -EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except -the passed context B<ctx> does not have to be initialized, and it always -uses the default digest implementation. - -EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest -context B<ctx> is automatically cleaned up. - -EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination -B<out> does not have to be initialized. - -EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest -when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the -hash. - -EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the -message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. - -EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER -representing the given message digest when passed an B<EVP_MD> structure. -For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is -normally used when setting ASN1 OIDs. - -EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed -B<EVP_MD_CTX>. - -EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated -with this digest. For example EVP_sha1() is associated with RSA so this will -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_sha1(), EVP_sha224(), EVP_sha256(), -EVP_sha384(), EVP_sha512(), EVP_mdc2(), EVP_ripemd160(), EVP_blake2b_512(), and -EVP_blake2s_256() 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. - -=head1 RETURN VALUES - -EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for -success and 0 for failure. - -EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure. - -EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the -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_sha1(), -EVP_mdc2(), EVP_ripemd160(), EVP_blake2b_512(), and EVP_blake2s_256() 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. - -=head1 NOTES - -The B<EVP> interface to message digests should almost always be used in -preference to the low level interfaces. This is because the code then becomes -transparent to the digest used and much more flexible. - -New applications should use the SHA2 digest algorithms such as SHA256. -The other digest algorithms are still in common use. - -For most applications the B<impl> parameter to EVP_DigestInit_ex() will be -set to NULL to use the default digest implementation. - -The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are -obsolete but are retained to maintain compatibility with existing code. New -applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and -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. - -If digest contexts are not cleaned up after use -memory leaks will occur. - -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 - -This example digests the data "Test Message\n" and "Hello World\n", using the -digest name passed on the command line. - - #include <stdio.h> - #include <openssl/evp.h> - - main(int argc, char *argv[]) - { - EVP_MD_CTX *mdctx; - const EVP_MD *md; - char mess1[] = "Test Message\n"; - char mess2[] = "Hello World\n"; - unsigned char md_value[EVP_MAX_MD_SIZE]; - int md_len, i; - - if(!argv[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); - } - - 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_free(mdctx); - - printf("Digest is: "); - for (i = 0; i < md_len; i++) - printf("%02x", md_value[i]); - printf("\n"); - - exit(0); - } - -=head1 SEE ALSO - -L<dgst(1)>, -L<evp(3)> - -=head1 HISTORY - -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_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. The legacy EVP_dss1() -was removed 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/doc/crypto/EVP_DigestSignInit.pod b/doc/crypto/EVP_DigestSignInit.pod deleted file mode 100644 index 13d6c7b3c1..0000000000 --- a/doc/crypto/EVP_DigestSignInit.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, - 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); - -=head1 DESCRIPTION - -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 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 -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 -the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the -B<siglen> parameter should contain the length of the B<sig> buffer, if the -call is successful the signature is written to B<sig> and the amount of data -written to B<siglen>. - -=head1 RETURN VALUES - -EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() 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. - -The error codes can be obtained from L<ERR_get_error(3)>. - -=head1 NOTES - -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. - -In previous versions of OpenSSL there was a link between message digest types -and public key algorithms. This meant that "clone" digests such as EVP_dss1() -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. - -The call to EVP_DigestSignFinal() internally finalizes a copy of the digest -context. This means that calls to EVP_DigestSignUpdate() and -EVP_DigestSignFinal() can be called later to digest and sign additional data. - -Since only a copy of the digest context is ever finalized the context must -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -The use of EVP_PKEY_size() with these functions is discouraged because some -signature operations may have a signature length which depends on the -parameters set. As a result EVP_PKEY_size() would have to return a value -which indicates the maximum possible signature for any set of parameters. - -=head1 SEE ALSO - -L<EVP_DigestVerifyInit(3)>, -L<EVP_DigestInit(3)>, L<err(3)>, -L<evp(3)>, L<hmac(3)>, L<md2(3)>, -L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>, -L<sha(3)>, L<dgst(1)> - -=head1 HISTORY - -EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() -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/doc/crypto/EVP_DigestVerifyInit.pod b/doc/crypto/EVP_DigestVerifyInit.pod deleted file mode 100644 index c665d12772..0000000000 --- a/doc/crypto/EVP_DigestVerifyInit.pod +++ /dev/null @@ -1,91 +0,0 @@ -=pod - -=head1 NAME - -EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signature verification functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, - 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); - -=head1 DESCRIPTION - -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 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. - -EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the -verification context B<ctx>. This function can be called several times on the -same B<ctx> to include additional data. This function is currently implemented -using a macro. - -EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in -B<sig> of length B<siglen>. - -=head1 RETURN VALUES - -EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 -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 -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)>. - -=head1 NOTES - -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. - -In previous versions of OpenSSL there was a link between message digest types -and public key algorithms. This meant that "clone" digests such as EVP_dss1() -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. - -The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest -context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can -be called later to digest and verify additional data. - -Since only a copy of the digest context is ever finalized the context must -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -=head1 SEE ALSO - -L<EVP_DigestSignInit(3)>, -L<EVP_DigestInit(3)>, L<err(3)>, -L<evp(3)>, L<hmac(3)>, L<md2(3)>, -L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>, -L<sha(3)>, L<dgst(1)> - -=head1 HISTORY - -EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() -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/doc/crypto/EVP_EncodeInit.pod b/doc/crypto/EVP_EncodeInit.pod deleted file mode 100644 index d919b14b29..0000000000 --- a/doc/crypto/EVP_EncodeInit.pod +++ /dev/null @@ -1,162 +0,0 @@ -=pod - -=head1 NAME - -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); - 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); - - void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); - int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, - const unsigned char *in, int inl); - int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned - char *out, int *outl); - int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); - -=head1 DESCRIPTION - -The EVP encode routines provide a high level interface to base 64 encoding and -decoding. Base 64 encoding converts binary data into a printable form that uses -the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3 -bytes of binary data provided 4 bytes of base 64 encoded data will be produced -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 -final block (which may be less than 48 bytes) will output 4 bytes for every 3 -bytes of input. If the data length is not divisible by 3 then a full 4 bytes is -still output for the final 1 or 2 bytes of input. Similarly a newline character -will also be output. - -EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation. - -EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by -B<in>. The output is stored in the buffer B<out> and the number of bytes output -is stored in B<*outl>. It is the caller's responsibility to ensure that the -buffer at B<out> is sufficiently large to accommodate the output data. Only full -blocks of data (48 bytes) will be immediately processed and output by this -function. Any remainder is held in the B<ctx> object and will be processed by a -subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the -required size of the output buffer add together the value of B<inl> with the -amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore -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 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 -data will be stored in B<out> and the length of the data written will be stored -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 -encoded as a final block of data and the output is padded such that it is always -divisible by 4. Additionally a NUL terminator character will be added. For -example if 16 bytes of input data is provided then 24 bytes of encoded data is -created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of -the data generated I<without> the NUL terminator is returned from the function. - -EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation. - -EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed -to by B<in>. The output is stored in the buffer B<out> and the number of bytes -output is stored in B<*outl>. It is the caller's responsibility to ensure that -the buffer at B<out> is sufficiently large to accommodate the output data. This -function will attempt to decode as much data as possible in 4 byte chunks. Any -whitespace, newline or carriage return characters are ignored. Any partial chunk -of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in -the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If -any illegal base 64 characters are encountered or if the base 64 padding -character "=" is encountered in the middle of the data then the function returns --1 to indicate an error. A return value of 0 or 1 indicates successful -processing of the data. A return value of 0 additionally indicates that the last -input data characters processed included the base 64 padding character "=" and -therefore no more non-padding character data is expected to be processed. For -every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and -line feeds), 3 bytes of binary output data will be produced (or less at the end -of the data where the padding character "=" has been used). - -EVP_DecodeFinal() must be called at the end of a decoding operation. If there -is any unprocessed data still in B<ctx> then the input data must not have been -a multiple of 4 and therefore an error has occurred. The function will return -1 -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 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 -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. - -EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned -then no more non-padding base 64 characters are expected. - -EVP_DecodeFinal() returns -1 on error or 1 on success. - -EVP_DecodeBlock() returns the length of the data decoded or -1 on error. - -=head1 SEE ALSO - -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/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod deleted file mode 100644 index d981620908..0000000000 --- a/doc/crypto/EVP_EncryptInit.pod +++ /dev/null @@ -1,650 +0,0 @@ -=pod - -=head1 NAME - -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, -EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, -EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, -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_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_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_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 cipher routines - -=for comment generic - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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, unsigned char *key, unsigned char *iv); - int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - - int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - ENGINE *impl, unsigned char *key, unsigned char *iv); - int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - ENGINE *impl, unsigned char *key, unsigned char *iv, int enc); - int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv); - int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - - int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv); - int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv, int enc); - int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - 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); - - const EVP_CIPHER *EVP_get_cipherbyname(const char *name); - 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); - - 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); - -=head1 DESCRIPTION - -The EVP cipher routines are a high level interface to certain -symmetric ciphers. - -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 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 -and B<iv> is the IV to use (if necessary), the actual number of bytes -used for the key and IV depends on the cipher. It is possible to set -all parameters to NULL except B<type> in an initial call and supply -the remaining parameters in subsequent calls, all of which have B<type> -set to NULL. This is done when the default cipher parameters are not -appropriate. - -EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and -writes the encrypted version to B<out>. This function can be called -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>. 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 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 -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. - -EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the -corresponding decryption operations. EVP_DecryptFinal() will return an -error code if padding is enabled and the final block is not correctly -formatted. The parameters and restrictions are identical to the encryption -operations except that if padding is enabled the decrypted data buffer B<out> -passed to EVP_DecryptUpdate() should have sufficient room for -(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in -which case B<inl> bytes is sufficient. - -EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are -functions that can be used for decryption or encryption. The operation -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_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 -EVP_CipherInit_ex() except the B<ctx> parameter does not need to be -initialized and they always use the default cipher implementation. - -EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are -identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and -EVP_CipherFinal_ex(). In previous releases they also cleaned up -the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean() -must be called to free any context resources. - -EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() -return an EVP_CIPHER structure when passed a cipher name, a NID or an -ASN1_OBJECT structure. - -EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when -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. 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> -structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length -for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a -given cipher, the value of EVP_CIPHER_CTX_key_length() may be different -for variable key length ciphers. - -EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. -If the cipher is a fixed length cipher then attempting to set the key -length to any value other than the fixed value is an error. - -EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV -length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>. -It will return zero if the cipher does not use an IV. The constant -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_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 -cipher or context. This "type" is the actual NID of the cipher OBJECT -IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and -128 bit RC2 have the same NID. If the cipher does not have an object -identifier or does not have ASN1 support this function will return -B<NID_undef>. - -EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed -an B<EVP_CIPHER_CTX> structure. - -EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode: -EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or -EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then -EVP_CIPH_STREAM_CIPHER is returned. - -EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based -on the passed cipher. This will typically include any parameters and an -IV. The cipher IV (if any) must be set when this call is made. This call -should be made before the cipher is actually "used" (before any -EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function -may fail if the cipher does not have any ASN1 support. - -EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 -AlgorithmIdentifier "parameter". The precise effect depends on the cipher -In the case of RC2, for example, it will set the IV and effective key length. -This function should be called after the base cipher type is set but before -the key is set. For example EVP_CipherInit() will be called with the IV and -key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally -EVP_CipherInit() again with all parameters except the key set to NULL. It is -possible for this function to fail if the cipher does not have any ASN1 support -or the parameters cannot be set (for example the RC2 effective key length -is not supported. - -EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined -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. - -EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure. -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_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. - -EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. - -EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block -size. - -EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key -length. - -EVP_CIPHER_CTX_set_padding() always returns 1. - -EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV -length or zero if the cipher does not use an IV. - -EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's -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 greater -than zero for success and zero or a negative number. - -=head1 CIPHER LISTING - -All algorithms have a fixed key length unless otherwise stated. - -=over 4 - -=item EVP_enc_null() - -Null cipher: does nothing. - -=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() - -AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively. - -=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(), 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() - -DESX algorithm in CBC mode. - -=item EVP_rc4() - -RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. - -=item EVP_rc4_40() - -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(), EVP_idea_cfb(), EVP_idea_ofb() - -IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. - -=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(), 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(), 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(), 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(), 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(), 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 -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(), 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. - -=back - -=head1 GCM and OCB Modes - -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 -parameter B<out> set to B<NULL>. - -When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() -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 both GCM and OCB modes: - - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_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. - - 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). 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_AEAD_SET_TAG, taglen, tag); - -Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal -when decrypting data and must be made B<before> any data is processed (e.g. -before any EVP_DecryptUpdate() call). 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. - -See L</EXAMPLES> below for an example of the use of GCM mode. - -=head1 CCM Mode - -The behaviour of CCM mode ciphers is similar to GCM mode but with a few -additional requirements and different ctrl values. - -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>) -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_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. -The tag length is often referred to as B<M>. If not set a default value is -used (12 for AES). - - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL); - -Sets the CCM B<L> value. If not set a default is used (8 for AES). - - 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 -preference to the low level interfaces. This is because the code then becomes -transparent to the cipher used and much more flexible. Additionally, the -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 -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 -encrypted then 5 padding bytes of value 5 will be added. - -When decrypting the final block is checked to see if it has the correct form. - -Although the decryption operation can produce an error if padding is enabled, -it is not a strong test that the input data or key is correct. A random block -has better than 1 in 256 chance of being of the correct format and problems with -the input data earlier on will not produce a final decrypt error. - -If padding is disabled then the decryption operation will always succeed if -the total amount of data decrypted is a multiple of the block size. - -The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), -EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for -compatibility with existing code. New code should use EVP_EncryptInit_ex(), -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 -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 -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 -for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. - -=head1 EXAMPLES - -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; - - 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 - -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 */ - 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)> - -=head1 HISTORY - -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-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/doc/crypto/EVP_MD_meth_new.pod b/doc/crypto/EVP_MD_meth_new.pod deleted file mode 100644 index c15a31e7fc..0000000000 --- a/doc/crypto/EVP_MD_meth_new.pod +++ /dev/null @@ -1,170 +0,0 @@ -=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, EVP_MD_CTX_md_data -- 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)); - void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx); - 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 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. The functions described here were added in OpenSSL version 1.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/doc/crypto/EVP_OpenInit.pod b/doc/crypto/EVP_OpenInit.pod deleted file mode 100644 index ff84490a42..0000000000 --- a/doc/crypto/EVP_OpenInit.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption - -=head1 SYNOPSIS - - #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_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, - int *outl); - -=head1 DESCRIPTION - -The EVP envelope routines are a high level interface to envelope -decryption. They decrypt a public key encrypted symmetric key and -then decrypt data using it. - -EVP_OpenInit() initializes a cipher context B<ctx> for decryption -with cipher B<type>. It decrypts the encrypted symmetric key of length -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)> manual -page. - -=head1 NOTES - -It is possible to call EVP_OpenInit() twice in the same way as -EVP_DecryptInit(). The first call should have B<priv> set to NULL -and (after setting any cipher parameters) it should be called again -with B<type> set to NULL. - -If the cipher passed in the B<type> parameter is a variable length -cipher then the key length will be set to the value of the recovered -key length. If the cipher is a fixed length cipher then the recovered -key length must match the fixed cipher length. - -=head1 RETURN VALUES - -EVP_OpenInit() returns 0 on error or a non zero integer (actually the -recovered secret key size) if successful. - -EVP_OpenUpdate() returns 1 for success or 0 for failure. - -EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success. - -=head1 SEE ALSO - -L<evp(3)>, L<rand(3)>, -L<EVP_EncryptInit(3)>, -L<EVP_SealInit(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/doc/crypto/EVP_PKEY_CTX_ctrl.pod b/doc/crypto/EVP_PKEY_CTX_ctrl.pod deleted file mode 100644 index a30450bb46..0000000000 --- a/doc/crypto/EVP_PKEY_CTX_ctrl.pod +++ /dev/null @@ -1,154 +0,0 @@ -=pod - -=head1 NAME - -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, -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 EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, - const char *value); - - #include <openssl/rsa.h> - - int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); - - int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); - int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); - int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); - int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); - - #include <openssl/dsa.h> - int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); - - #include <openssl/dh.h> - int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); - int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); - - #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 - -The function EVP_PKEY_CTX_ctrl() sends a control operation to the context -B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter -B<optype> is a mask indicating which operations the control can be applied to. -The control command is indicated in B<cmd> and any additional arguments in -B<p1> and B<p2>. - -Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will -instead call one of the algorithm specific macros below. - -The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm -specific control operation to a context B<ctx> in string form. This is -intended to be used for options specified on the command line or in text -files. The commands supported are documented in the openssl utility -command line pages for the option B<-pkeyopt> which is supported by the -B<pkeyutl>, B<genpkey> and B<req> commands. - -All the remaining "functions" are implemented as macros. - -The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used -in a signature. It can be used with any public key algorithm supporting -signature operations. - -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_PKCS1_PSS_PADDING (sign and verify only). - -Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() -is used. If this macro is called for PKCS#1 padding the plaintext buffer is -an actual digest value and is encapsulated in a DigestInfo structure according -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. - -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 -values are supported: -1 sets the salt length to the digest length. When -signing -2 sets the salt length to the maximum permissible value. When -verifying -2 causes the salt length to be automatically determined based on the -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 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 -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 -for DSA parameter generation to B<bits>. If not specified 1024 is used. - -The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH -prime parameter B<p> for DH parameter generation. If this macro is not called -then 1024 is used. - -The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen> -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 - -EVP_PKEY_CTX_ctrl() and its macros return a positive value 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 SEE ALSO - -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/doc/crypto/EVP_PKEY_CTX_new.pod b/doc/crypto/EVP_PKEY_CTX_new.pod deleted file mode 100644 index eff94cd943..0000000000 --- a/doc/crypto/EVP_PKEY_CTX_new.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); - EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); - EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); - void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); - -=head1 DESCRIPTION - -The EVP_PKEY_CTX_new() function allocates public key algorithm context using -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 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 - -The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used -by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between -threads: that is it is not permissible to use the same context simultaneously -in two threads. - -=head1 RETURN VALUES - -EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either -the newly allocated B<EVP_PKEY_CTX> structure of B<NULL> if an error occurred. - -EVP_PKEY_CTX_free() does not return a value. - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod b/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod deleted file mode 100644 index 61e0eec528..0000000000 --- a/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod +++ /dev/null @@ -1,128 +0,0 @@ -=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/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod b/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod deleted file mode 100644 index 0d57f9fb6a..0000000000 --- a/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod +++ /dev/null @@ -1,108 +0,0 @@ -=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, seed, seedlen) - 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 EVP_PKEY_derive(). - -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/doc/crypto/EVP_PKEY_cmp.pod b/doc/crypto/EVP_PKEY_cmp.pod deleted file mode 100644 index 270d635ce2..0000000000 --- a/doc/crypto/EVP_PKEY_cmp.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, -EVP_PKEY_cmp - public key parameter and comparison functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); - int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); - - int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); - int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); - -=head1 DESCRIPTION - -The function EVP_PKEY_missing_parameters() returns 1 if the public key -parameters of B<pkey> are missing and 0 if they are present or the algorithm -doesn't use parameters. - -The function EVP_PKEY_copy_parameters() copies the parameters from key -B<from> to key B<to>. An error is returned if the parameters are missing in -B<from> or present in both B<from> and B<to> and mismatch. If the parameters -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 parameters -(if present) of keys B<a> and B<b>. - -=head1 NOTES - -The main purpose of the functions EVP_PKEY_missing_parameters() and -EVP_PKEY_copy_parameters() is to handle public keys in certificates where the -parameters are sometimes omitted from a public key if they are inherited from -the CA that signed it. - -Since OpenSSL private keys contain public key components too the function -EVP_PKEY_cmp() can also be used to determine if a private key matches -a public key. - -=head1 RETURN VALUES - -The function EVP_PKEY_missing_parameters() returns 1 if the public key -parameters of B<pkey> are missing and 0 if they are present or the algorithm -doesn't use parameters. - -These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for -failure. - -The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the -keys match, 0 if they don't match, -1 if the key types are different and --2 if the operation is not supported. - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_decrypt.pod b/doc/crypto/EVP_PKEY_decrypt.pod deleted file mode 100644 index ca732ed0f9..0000000000 --- a/doc/crypto/EVP_PKEY_decrypt.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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); - -=head1 DESCRIPTION - -The EVP_PKEY_decrypt_init() function initializes a public key algorithm -context using key B<pkey> for a decryption operation. - -The EVP_PKEY_decrypt() function performs a public key decryption operation -using B<ctx>. The data to be decrypted is specified using the B<in> and -B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output -buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then -before the call the B<outlen> parameter should contain the length of the -B<out> buffer, if the call is successful the decrypted data is written to -B<out> and the amount of data written to B<outlen>. - -=head1 NOTES - -After the call to EVP_PKEY_decrypt_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_decrypt() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() 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 - -Decrypt data using OAEP (for RSA keys): - - #include <openssl/evp.h> - #include <openssl/rsa.h> - - EVP_PKEY_CTX *ctx; - unsigned char *out, *in; - 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 */ - if (EVP_PKEY_decrypt_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0) - /* Error */ - - out = OPENSSL_malloc(outlen); - - if (!out) - /* malloc failure */ - - if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0) - /* Error */ - - /* Decrypted data is outlen bytes written to buffer out */ - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_derive.pod b/doc/crypto/EVP_PKEY_derive.pod deleted file mode 100644 index f70a0b8d9b..0000000000 --- a/doc/crypto/EVP_PKEY_derive.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); - int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); - -=head1 DESCRIPTION - -The EVP_PKEY_derive_init() function initializes a public key algorithm -context using key B<pkey> for shared secret derivation. - -The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally -be a public key. - -The EVP_PKEY_derive() derives a shared secret using B<ctx>. -If B<key> is B<NULL> then the maximum size of the output buffer is written to -the B<keylen> parameter. If B<key> is not B<NULL> then before the call the -B<keylen> parameter should contain the length of the B<key> buffer, if the call -is successful the shared secret is written to B<key> and the amount of data -written to B<keylen>. - -=head1 NOTES - -After the call to EVP_PKEY_derive_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_derive() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_derive_init() and EVP_PKEY_derive() 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 - -Derive shared secret (for example DH or EC keys): - - #include <openssl/evp.h> - #include <openssl/rsa.h> - - EVP_PKEY_CTX *ctx; - unsigned char *skey; - size_t skeylen; - EVP_PKEY *pkey, *peerkey; - /* NB: assumes pkey, peerkey have been already set up */ - - ctx = EVP_PKEY_CTX_new(pkey); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_derive_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) - /* Error */ - - skey = OPENSSL_malloc(skeylen); - - if (!skey) - /* malloc failure */ - - if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) - /* Error */ - - /* Shared secret is skey bytes written to buffer skey */ - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_encrypt.pod b/doc/crypto/EVP_PKEY_encrypt.pod deleted file mode 100644 index 01336e128b..0000000000 --- a/doc/crypto/EVP_PKEY_encrypt.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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); - -=head1 DESCRIPTION - -The EVP_PKEY_encrypt_init() function initializes a public key algorithm -context using key B<pkey> for an encryption operation. - -The EVP_PKEY_encrypt() function performs a public key encryption operation -using B<ctx>. The data to be encrypted is specified using the B<in> and -B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output -buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then -before the call the B<outlen> parameter should contain the length of the -B<out> buffer, if the call is successful the encrypted data is written to -B<out> and the amount of data written to B<outlen>. - -=head1 NOTES - -After the call to EVP_PKEY_encrypt_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_encrypt() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() 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 - -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> - #include <openssl/rsa.h> - #include <openssl/engine.h> - - EVP_PKEY_CTX *ctx; - ENGINE *eng; - unsigned char *out, *in; - 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); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_encrypt_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0) - /* Error */ - - out = OPENSSL_malloc(outlen); - - if (!out) - /* malloc failure */ - - if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0) - /* Error */ - - /* Encrypted data is outlen bytes written to buffer out */ - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_get_default_digest_nid.pod b/doc/crypto/EVP_PKEY_get_default_digest_nid.pod deleted file mode 100644 index 3dce5c59a8..0000000000 --- a/doc/crypto/EVP_PKEY_get_default_digest_nid.pod +++ /dev/null @@ -1,50 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_get_default_digest_nid - get default signature digest - -=head1 SYNOPSIS - - #include <openssl/evp.h> - int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); - -=head1 DESCRIPTION - -The EVP_PKEY_get_default_digest_nid() function sets B<pnid> to the default -message digest NID for the public key signature operations associated with key -B<pkey>. - -=head1 NOTES - -For all current standard OpenSSL public key algorithms SHA1 is returned. - -=head1 RETURN VALUES - -The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest -is advisory (that is other digests can be used) and 2 if it is mandatory (other -digests can not be used). It returns 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 SEE ALSO - -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/doc/crypto/EVP_PKEY_keygen.pod b/doc/crypto/EVP_PKEY_keygen.pod deleted file mode 100644 index 5b8b635cc5..0000000000 --- a/doc/crypto/EVP_PKEY_keygen.pod +++ /dev/null @@ -1,173 +0,0 @@ -=pod - -=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_PKEY_CTX_set_app_data, -EVP_PKEY_CTX_get_app_data - key and parameter generation functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); - int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); - - typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); - - void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); - EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); - - int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); - - void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); - void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); - -=head1 DESCRIPTION - -The EVP_PKEY_keygen_init() function initializes a public key algorithm -context using key B<pkey> for a key generation operation. - -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 -except parameters are generated. - -The function EVP_PKEY_set_cb() sets the key or parameter generation callback -to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter -generation callback. - -The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated -with the generation operation. If B<idx> is -1 the total number of -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 generation operation is aborted and an -error occurs. This might occur during a time consuming operation where -a user clicks on a "cancel" button. - -The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set -and retrieve an opaque pointer. This can be used to set some application -defined value which can be retrieved in the callback: for example a handle -which is used to update a "progress dialog". - -=head1 NOTES - -After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm -specific control operations can be performed to set any appropriate parameters -for the operation. - -The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than -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 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. - -The operation performed by key or parameter generation depends on the algorithm -used. In some cases (e.g. EC with a supplied named curve) the "generation" -option merely sets the appropriate fields in an EVP_PKEY structure. - -In OpenSSL an EVP_PKEY structure containing a private key also contains the -public key components and parameters (if any). An OpenSSL private key is -equivalent to what some libraries call a "key pair". A private key can be used -in functions which require the use of a public key or parameters. - -=head1 RETURN VALUES - -EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and -EVP_PKEY_paramgen() 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 EXAMPLES - -Generate a 2048 bit RSA key: - - #include <openssl/evp.h> - #include <openssl/rsa.h> - - EVP_PKEY_CTX *ctx; - EVP_PKEY *pkey = NULL; - ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_keygen_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) - /* Error */ - - /* Generate key */ - if (EVP_PKEY_keygen(ctx, &pkey) <= 0) - /* Error */ - -Generate a key from a set of parameters: - - #include <openssl/evp.h> - #include <openssl/rsa.h> - - EVP_PKEY_CTX *ctx; - EVP_PKEY *pkey = NULL, *param; - /* Assumed param is set up already */ - ctx = EVP_PKEY_CTX_new(param); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_keygen_init(ctx) <= 0) - /* Error */ - - /* Generate key */ - if (EVP_PKEY_keygen(ctx, &pkey) <= 0) - /* Error */ - -Example of generation callback for OpenSSL public key implementations: - - /* Application data is a BIO to output status to */ - - 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; - } - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_new.pod b/doc/crypto/EVP_PKEY_new.pod deleted file mode 100644 index 956d699002..0000000000 --- a/doc/crypto/EVP_PKEY_new.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -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 reference count is set to B<1>. - -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 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 or -B<NULL> if an error occurred. - -EVP_PKEY_up_ref() returns 1 for success and 0 for failure. - -=head1 SEE ALSO - -L<EVP_PKEY_set1_RSA(3)> - -=head1 HISTORY - -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/doc/crypto/EVP_PKEY_print_private.pod b/doc/crypto/EVP_PKEY_print_private.pod deleted file mode 100644 index 9f1d324f81..0000000000 --- a/doc/crypto/EVP_PKEY_print_private.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -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 EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); - int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); - -=head1 DESCRIPTION - -The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and -EVP_PKEY_print_params() print out the public, private or parameter components -of key B<pkey> respectively. The key is sent to BIO B<out> in human readable -form. The parameter B<indent> indicated how far the printout should be indented. - -The B<pctx> parameter allows the print output to be finely tuned by using -ASN1 printing options. If B<pctx> is set to NULL then default values will -be used. - -=head1 NOTES - -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 -only those contained in the key will be printed. For example passing a public -key to EVP_PKEY_print_private() will only print the public components. - -=head1 RETURN VALUES - -These functions all 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 SEE ALSO - -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/doc/crypto/EVP_PKEY_set1_RSA.pod b/doc/crypto/EVP_PKEY_set1_RSA.pod deleted file mode 100644 index e1b7110fe5..0000000000 --- a/doc/crypto/EVP_PKEY_set1_RSA.pod +++ /dev/null @@ -1,120 +0,0 @@ -=pod - -=head1 NAME - -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_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 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); - - 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); - - 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); - -=head1 DESCRIPTION - -EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and -EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>. - -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_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>. - -=head1 NOTES - -In accordance with the OpenSSL naming convention the key obtained -from or assigned to the B<pkey> using the B<1> functions must be -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). - -=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 -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. - -=head1 SEE ALSO - -L<EVP_PKEY_new(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/doc/crypto/EVP_PKEY_sign.pod b/doc/crypto/EVP_PKEY_sign.pod deleted file mode 100644 index 9b3c8d4593..0000000000 --- a/doc/crypto/EVP_PKEY_sign.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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); - -=head1 DESCRIPTION - -The EVP_PKEY_sign_init() function initializes a public key algorithm -context using key B<pkey> for a signing operation. - -The EVP_PKEY_sign() function performs a public key signing operation -using B<ctx>. The data to be signed is specified using the B<tbs> and -B<tbslen> parameters. If B<sig> is B<NULL> then the maximum size of the output -buffer is written to the B<siglen> parameter. If B<sig> is not B<NULL> then -before the call the B<siglen> parameter should contain the length of the -B<sig> buffer, if the call is successful the signature is written to -B<sig> and the amount of data written to B<siglen>. - -=head1 NOTES - -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)> 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)>). - -The function EVP_PKEY_sign() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_sign_init() and EVP_PKEY_sign() 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 - -Sign data using RSA with PKCS#1 padding and SHA256 digest: - - #include <openssl/evp.h> - #include <openssl/rsa.h> - - EVP_PKEY_CTX *ctx; - /* md is a SHA-256 digest in this example. */ - unsigned char *md, *sig; - size_t mdlen = 32, siglen; - EVP_PKEY *signing_key; - - /* - * NB: assumes signing_key and md are set up before the next - * step. signing_key must be an RSA private key and md must - * point to the SHA-256 digest to be signed. - */ - ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_sign_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) - /* Error */ - - sig = OPENSSL_malloc(siglen); - - if (!sig) - /* malloc failure */ - - if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) - /* Error */ - - /* Signature is siglen bytes written to buffer sig */ - - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_verify.pod b/doc/crypto/EVP_PKEY_verify.pod deleted file mode 100644 index e84f880419..0000000000 --- a/doc/crypto/EVP_PKEY_verify.pod +++ /dev/null @@ -1,100 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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); - -=head1 DESCRIPTION - -The EVP_PKEY_verify_init() function initializes a public key algorithm -context using key B<pkey> for a signature verification operation. - -The EVP_PKEY_verify() function performs a public key verification operation -using B<ctx>. The signature is specified using the B<sig> and -B<siglen> parameters. The verified data (i.e. the data believed originally -signed) is specified using the B<tbs> and B<tbslen> parameters. - -=head1 NOTES - -After the call to EVP_PKEY_verify_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_verify() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was -successful and 0 if it failed. Unlike other functions the return value 0 from -EVP_PKEY_verify() only indicates that the signature did not not verify -successfully (that is tbs did not match the original data or the signature was -of invalid form) it is not an indication of a more serious error. - -A negative value indicates an error other that signature verification failure. -In particular a return value of -2 indicates the operation is not supported by -the public key algorithm. - -=head1 EXAMPLE - -Verify signature using PKCS#1 and SHA256 digest: - - #include <openssl/evp.h> - #include <openssl/rsa.h> - - EVP_PKEY_CTX *ctx; - unsigned char *md, *sig; - 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 */ - if (EVP_PKEY_verify_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ - - /* Perform operation */ - ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); - - /* ret == 1 indicates success, 0 verify failure and < 0 for some - * other error. - */ - -=head1 SEE ALSO - -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/doc/crypto/EVP_PKEY_verify_recover.pod b/doc/crypto/EVP_PKEY_verify_recover.pod deleted file mode 100644 index 837bc64ec2..0000000000 --- a/doc/crypto/EVP_PKEY_verify_recover.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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); - -=head1 DESCRIPTION - -The EVP_PKEY_verify_recover_init() function initializes a public key algorithm -context using key B<pkey> for a verify recover operation. - -The EVP_PKEY_verify_recover() function recovers signed data -using B<ctx>. The signature is specified using the B<sig> and -B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output -buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then -before the call the B<routlen> parameter should contain the length of the -B<rout> buffer, if the call is successful recovered data is written to -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 -used. - -Sometimes however it is useful to obtain the data originally signed using a -signing operation. Only certain public key algorithms can recover a signature -in this way (for example RSA in PKCS padding mode). - -After the call to EVP_PKEY_verify_recover_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_verify_recover() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() 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 - -Recover digest originally signed using PKCS#1 and SHA256 digest: - - #include <openssl/evp.h> - #include <openssl/rsa.h> - - EVP_PKEY_CTX *ctx; - unsigned char *rout, *sig; - 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 */ - if (EVP_PKEY_verify_recover_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0) - /* Error */ - - rout = OPENSSL_malloc(routlen); - - if (!rout) - /* malloc failure */ - - if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0) - /* Error */ - - /* Recovered data is routlen bytes written to buffer rout */ - -=head1 SEE ALSO - -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/doc/crypto/EVP_SealInit.pod b/doc/crypto/EVP_SealInit.pod deleted file mode 100644 index 30bd6808c1..0000000000 --- a/doc/crypto/EVP_SealInit.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=head1 NAME - -EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char **ek, int *ekl, unsigned char *iv, - EVP_PKEY **pubk, int npubk); - int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - -=head1 DESCRIPTION - -The EVP envelope routines are a high level interface to envelope -encryption. They generate a random key and IV (if required) then -"envelope" it by using public key encryption. Data can then be -encrypted using this key. - -EVP_SealInit() initializes a cipher context B<ctx> for encryption -with cipher B<type> using a random secret key and IV. B<type> is normally -supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted -using one or more public keys, this allows the same encrypted data to be -decrypted using any of the corresponding private keys. B<ek> is an array of -buffers where the public key encrypted secret key will be written, each buffer -must contain enough room for the corresponding encrypted key: that is -B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual -size of each encrypted secret key is written to the array B<ekl>. B<pubk> is -an array of B<npubk> public keys. - -The B<iv> parameter is a buffer where the generated IV is written to. It must -contain enough room for the corresponding cipher's IV, as determined by (for -example) EVP_CIPHER_iv_length(type). - -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)> manual -page. - -=head1 RETURN VALUES - -EVP_SealInit() returns 0 on error or B<npubk> if successful. - -EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for -failure. - -=head1 NOTES - -Because a random secret key is generated the random number generator -must be seeded before calling EVP_SealInit(). - -The public key must be RSA because it is the only OpenSSL public key -algorithm that supports key transport. - -Envelope encryption is the usual method of using public key encryption -on large amounts of data, this is because public key encryption is slow -but symmetric encryption is fast. So symmetric encryption is used for -bulk encryption and the small random symmetric key used is transferred -using public key encryption. - -It is possible to call EVP_SealInit() twice in the same way as -EVP_EncryptInit(). The first call should have B<npubk> set to 0 -and (after setting any cipher parameters) it should be called again -with B<type> set to NULL. - -=head1 SEE ALSO - -L<evp(3)>, L<rand(3)>, -L<EVP_EncryptInit(3)>, -L<EVP_OpenInit(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/doc/crypto/EVP_SignInit.pod b/doc/crypto/EVP_SignInit.pod deleted file mode 100644 index cfbfd5efd4..0000000000 --- a/doc/crypto/EVP_SignInit.pod +++ /dev/null @@ -1,110 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_size, -EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing -functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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); - - void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); - - int EVP_PKEY_size(EVP_PKEY *pkey); - -=head1 DESCRIPTION - -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 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 -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 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. - -EVP_SignInit() initializes a signing context B<ctx> to use the default -implementation of digest B<type>. - -EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual -signature returned by EVP_SignFinal() may be smaller. - -=head1 RETURN VALUES - -EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1 -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)>. - -=head1 NOTES - -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)>. - -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. - -The call to EVP_SignFinal() internally finalizes a copy of the digest context. -This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called -later to digest and sign additional data. - -Since only a copy of the digest context is ever finalized the context must -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -=head1 BUGS - -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 -relating to the private key (for example an unsuitable key and digest -combination) will not be indicated until after potentially large amounts of -data have been passed through EVP_SignUpdate(). - -It is not possible to change the signing parameters using these function. - -The previous two bugs are fixed in the newer EVP_SignDigest*() function. - -=head1 SEE ALSO - -L<EVP_VerifyInit(3)>, -L<EVP_DigestInit(3)>, L<err(3)>, -L<evp(3)>, L<hmac(3)>, L<md2(3)>, -L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>, -L<sha(3)>, L<dgst(1)> - -=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/doc/crypto/EVP_VerifyInit.pod b/doc/crypto/EVP_VerifyInit.pod deleted file mode 100644 index 518c05ea0a..0000000000 --- a/doc/crypto/EVP_VerifyInit.pod +++ /dev/null @@ -1,99 +0,0 @@ -=pod - -=head1 NAME - -EVP_VerifyInit_ex, -EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal -- EVP signature verification functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - 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_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); - -=head1 DESCRIPTION - -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 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 -same B<ctx> to include additional data. - -EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey> -and against the B<siglen> bytes at B<sigbuf>. - -EVP_VerifyInit() initializes verification context B<ctx> to use the default -implementation of digest B<type>. - -=head1 RETURN VALUES - -EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for -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)>. - -=head1 NOTES - -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)>. - -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. - -Since only a copy of the digest context is ever finalized the context must -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -=head1 BUGS - -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 -relating to the private key (for example an unsuitable key and digest -combination) will not be indicated until after potentially large amounts of -data have been passed through EVP_SignUpdate(). - -It is not possible to change the signing parameters using these function. - -The previous two bugs are fixed in the newer EVP_VerifyDigest*() function. - -=head1 SEE ALSO - -L<evp(3)>, -L<EVP_SignInit(3)>, -L<EVP_DigestInit(3)>, L<err(3)>, -L<evp(3)>, L<hmac(3)>, L<md2(3)>, -L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>, -L<sha(3)>, L<dgst(1)> - -=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/doc/crypto/HMAC.pod b/doc/crypto/HMAC.pod deleted file mode 100644 index 87f7e33086..0000000000 --- a/doc/crypto/HMAC.pod +++ /dev/null @@ -1,151 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/hmac.h> - - unsigned char *HMAC(const EVP_MD *evp_md, const void *key, - int key_len, const unsigned char *d, int n, - unsigned char *md, unsigned int *md_len); - - HMAC_CTX *HMAC_CTX_new(void); - int HMAC_CTX_reset(HMAC_CTX *ctx); - - int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, - 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_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 - -HMAC is a MAC (message authentication code), i.e. a keyed hash -function used for message authentication, which is based on a hash -function. - -HMAC() computes the message authentication code of the B<n> bytes at -B<d> using the hash function B<evp_md> and the key B<key> which is -B<key_len> bytes long. - -It places the result in B<md> (which must have space for the output of -the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes). -If B<md> is NULL, the digest is placed in a static array. The size of -the output is placed in B<md_len>, unless it is B<NULL>. - -B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. - -HMAC_CTX_new() creates a new HMAC_CTX in heap memory. - -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_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: - -HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash -function B<evp_md> and the key B<key> which is B<key_len> bytes -long. It is deprecated and only included for backward compatibility -with OpenSSL 0.9.6b. - -HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash -function B<evp_md> and key B<key>. If both are NULL (or B<evp_md> is the same -as the previous digest used by B<ctx> and B<key> is NULL) the existing key is -reused. B<ctx> must have been created with HMAC_CTX_new() before the first use -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<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. - -HMAC_Update() can be called repeatedly with chunks of the message to -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_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_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 - -RFC 2104 - -=head1 SEE ALSO - -L<sha(3)>, L<evp(3)> - -=head1 HISTORY - -HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL versions 1.1.0. - -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/doc/crypto/MD5.pod b/doc/crypto/MD5.pod deleted file mode 100644 index 78da750796..0000000000 --- a/doc/crypto/MD5.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, -MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions - -=head1 SYNOPSIS - - #include <openssl/md2.h> - - unsigned char *MD2(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD2_Init(MD2_CTX *c); - int MD2_Update(MD2_CTX *c, const unsigned char *data, - unsigned long len); - int MD2_Final(unsigned char *md, MD2_CTX *c); - - - #include <openssl/md4.h> - - unsigned char *MD4(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD4_Init(MD4_CTX *c); - int MD4_Update(MD4_CTX *c, const void *data, - unsigned long len); - int MD4_Final(unsigned char *md, MD4_CTX *c); - - - #include <openssl/md5.h> - - unsigned char *MD5(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD5_Init(MD5_CTX *c); - int MD5_Update(MD5_CTX *c, const void *data, - unsigned long len); - int MD5_Final(unsigned char *md, MD5_CTX *c); - -=head1 DESCRIPTION - -MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. - -MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest -of the B<n> bytes at B<d> and place it in B<md> (which must have space -for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 -bytes of output). If B<md> is NULL, the digest is placed in a static -array. - -The following functions may be used if the message is not completely -stored in memory: - -MD2_Init() initializes a B<MD2_CTX> structure. - -MD2_Update() can be called repeatedly with chunks of the message to -be hashed (B<len> bytes at B<data>). - -MD2_Final() places the message digest in B<md>, which must have space -for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>. - -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)> -etc. instead of calling the hash functions directly. - -=head1 NOTE - -MD2, MD4, and MD5 are recommended only for compatibility with existing -applications. In new applications, SHA-1 or RIPEMD-160 should be -preferred. - -=head1 RETURN VALUES - -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 -success, 0 otherwise. - -=head1 CONFORMING TO - -RFC 1319, RFC 1320, RFC 1321 - -=head1 SEE ALSO - -L<EVP_DigestInit(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/doc/crypto/MDC2_Init.pod b/doc/crypto/MDC2_Init.pod deleted file mode 100644 index f7db71b460..0000000000 --- a/doc/crypto/MDC2_Init.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function - -=head1 SYNOPSIS - - #include <openssl/mdc2.h> - - unsigned char *MDC2(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MDC2_Init(MDC2_CTX *c); - int MDC2_Update(MDC2_CTX *c, const unsigned char *data, - unsigned long len); - int MDC2_Final(unsigned char *md, MDC2_CTX *c); - -=head1 DESCRIPTION - -MDC2 is a method to construct hash functions with 128 bit output from -block ciphers. These functions are an implementation of MDC2 with -DES. - -MDC2() computes the MDC2 message digest of the B<n> -bytes at B<d> and places it in B<md> (which must have space for -MDC2_DIGEST_LENGTH == 16 bytes of output). If B<md> is NULL, the digest -is placed in a static array. - -The following functions may be used if the message is not completely -stored in memory: - -MDC2_Init() initializes a B<MDC2_CTX> structure. - -MDC2_Update() can be called repeatedly with chunks of the message to -be hashed (B<len> bytes at B<data>). - -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)> etc. instead of calling the -hash functions directly. - -=head1 RETURN VALUES - -MDC2() returns a pointer to the hash value. - -MDC2_Init(), MDC2_Update() and MDC2_Final() return 1 for success, 0 otherwise. - -=head1 CONFORMING TO - -ISO/IEC 10118-2, with DES - -=head1 SEE ALSO - -L<EVP_DigestInit(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/doc/crypto/OBJ_nid2obj.pod b/doc/crypto/OBJ_nid2obj.pod deleted file mode 100644 index 3ada6679cf..0000000000 --- a/doc/crypto/OBJ_nid2obj.pod +++ /dev/null @@ -1,198 +0,0 @@ -=pod - -=head1 NAME - -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); - - int OBJ_obj2nid(const ASN1_OBJECT *o); - int OBJ_ln2nid(const char *ln); - int OBJ_sn2nid(const char *sn); - - int OBJ_txt2nid(const char *s); - - 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 i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a); - - 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 - -The ASN1 object utility functions process ASN1_OBJECT structures which are -a representation of the ASN1 OBJECT IDENTIFIER (OID) type. -For convenience, OIDs are usually represented in source code as numeric -identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that -are generated when the library is built, and their corresponding NIDs -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 -an ASN1_OBJECT structure, its long name and its short name respectively, -or B<NULL> is an error occurred. - -OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID -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 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 -as well as numerical forms. If B<no_name> is 1 only the numerical form -is acceptable. - -OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation. -The representation is written as a null terminated string to B<buf> -at most B<buf_len> bytes are written, truncating the result if necessary. -The total amount of space required is returned. If B<no_name> is 0 then -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 -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_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 - -Objects in OpenSSL can have a short name, a long name and a numerical -identifier (NID) associated with them. A standard set of objects is -represented in an internal table. The appropriate values are defined -in the header file B<objects.h>. - -For example the OID for commonName has the following definitions: - - #define SN_commonName "CN" - #define LN_commonName "commonName" - #define NID_commonName 13 - -New objects can be added by calling OBJ_create(). - -Table objects have certain advantages over other objects: for example -their NIDs can be used in a C language switch statement. They are -also static constant structures which are shared: that is there -is only a single constant structure for each table object. - -Objects which are not in the table have the NID value NID_undef. - -Objects do not need to be in the internal tables to be processed, -the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical -form of an OID. - -Some objects are used to represent algorithms which do not have a -corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently -exists for a particular algorithm). As a result they B<cannot> be encoded or -decoded as part of ASN.1 structures. Applications can determine if there -is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero. - -These functions cannot return B<const> because an B<ASN1_OBJECT> can -represent both an internal, constant, OID and a dynamically-created one. -The latter cannot be constant because it needs to be freed after use. - -=head1 EXAMPLES - -Create an object for B<commonName>: - - ASN1_OBJECT *o; - o = OBJ_nid2obj(NID_commonName); - -Check if an object is B<commonName> - - if (OBJ_obj2nid(obj) == NID_commonName) - /* Do something */ - -Create a new NID and initialize an object from it: - - int new_nid; - ASN1_OBJECT *obj; - - 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 -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 -be set to a positive value. A buffer length of 80 should be more -than enough to handle any OID encountered in practice. - -=head1 RETURN VALUES - -OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an -error occurred. - -OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> -on error. - -OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return -a NID or B<NID_undef> on error. - -=head1 SEE ALSO - -L<ERR_get_error(3)> - -=head1 HISTORY - -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/doc/crypto/OCSP_REQUEST_new.pod b/doc/crypto/OCSP_REQUEST_new.pod deleted file mode 100644 index 97c2337d10..0000000000 --- a/doc/crypto/OCSP_REQUEST_new.pod +++ /dev/null @@ -1,118 +0,0 @@ -=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/doc/crypto/OCSP_cert_to_id.pod b/doc/crypto/OCSP_cert_to_id.pod deleted file mode 100644 index 0e37937fea..0000000000 --- a/doc/crypto/OCSP_cert_to_id.pod +++ /dev/null @@ -1,89 +0,0 @@ -=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/doc/crypto/OCSP_request_add1_nonce.pod b/doc/crypto/OCSP_request_add1_nonce.pod deleted file mode 100644 index dab42c67be..0000000000 --- a/doc/crypto/OCSP_request_add1_nonce.pod +++ /dev/null @@ -1,84 +0,0 @@ -=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/doc/crypto/OCSP_resp_find_status.pod b/doc/crypto/OCSP_resp_find_status.pod deleted file mode 100644 index 36f66a858f..0000000000 --- a/doc/crypto/OCSP_resp_find_status.pod +++ /dev/null @@ -1,139 +0,0 @@ -=pod - -=head1 NAME - -OCSP_resp_get0_certs, -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_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_id() gets the responder id of <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. - -=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/doc/crypto/OCSP_response_status.pod b/doc/crypto/OCSP_response_status.pod deleted file mode 100644 index 81946a639b..0000000000 --- a/doc/crypto/OCSP_response_status.pod +++ /dev/null @@ -1,100 +0,0 @@ -=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 version 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/doc/crypto/OCSP_sendreq_new.pod b/doc/crypto/OCSP_sendreq_new.pod deleted file mode 100644 index c7fdc9b12e..0000000000 --- a/doc/crypto/OCSP_sendreq_new.pod +++ /dev/null @@ -1,122 +0,0 @@ -=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/doc/crypto/OPENSSL_Applink.pod b/doc/crypto/OPENSSL_Applink.pod deleted file mode 100644 index d3a461ba39..0000000000 --- a/doc/crypto/OPENSSL_Applink.pod +++ /dev/null @@ -1,31 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_Applink - glue between OpenSSL BIO and Win32 compiler run-time - -=head1 SYNOPSIS - - __declspec(dllexport) void **OPENSSL_Applink(); - -=head1 DESCRIPTION - -OPENSSL_Applink is application-side interface which provides a glue -between OpenSSL BIO layer and Win32 compiler run-time environment. -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 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/doc/crypto/OPENSSL_LH_COMPFUNC.pod b/doc/crypto/OPENSSL_LH_COMPFUNC.pod deleted file mode 100644 index e760ae3be7..0000000000 --- a/doc/crypto/OPENSSL_LH_COMPFUNC.pod +++ /dev/null @@ -1,239 +0,0 @@ -=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/doc/crypto/OPENSSL_LH_stats.pod b/doc/crypto/OPENSSL_LH_stats.pod deleted file mode 100644 index c454a47eef..0000000000 --- a/doc/crypto/OPENSSL_LH_stats.pod +++ /dev/null @@ -1,64 +0,0 @@ -=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/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/doc/crypto/OPENSSL_VERSION_NUMBER.pod deleted file mode 100644 index 9cc1ed1d9c..0000000000 --- a/doc/crypto/OPENSSL_VERSION_NUMBER.pod +++ /dev/null @@ -1,106 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_VERSION_NUMBER, OpenSSL_version, -OpenSSL_version_num - get OpenSSL version number - -=head1 SYNOPSIS - - #include <openssl/opensslv.h> - #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL - - #include <openssl/crypto.h> - - unsigned long OpenSSL_version_num(); - const char *OpenSSL_version(int t); - -=head1 DESCRIPTION - -OPENSSL_VERSION_NUMBER is a numeric release version identifier: - - MNNFFPPS: major minor fix patch status - -The status nibble has one of the values 0 for development, 1 to e for betas -1 to 14, and f for release. - -for example - - 0x000906000 == 0.9.6 dev - 0x000906023 == 0.9.6b beta 3 - 0x00090605f == 0.9.6e release - -Versions prior to 0.9.3 have identifiers E<lt> 0x0930. -Versions between 0.9.3 and 0.9.5 had a version identifier with this -interpretation: - - MMNNFFRBB major minor fix final beta/patch - -for example - - 0x000904100 == 0.9.4 release - 0x000905000 == 0.9.5 dev - -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. - -OpenSSL_version() returns different strings depending on B<t>: - -=over 4 - -=item OPENSSL_VERSION - -The text variant of the version number and the release date. For example, -"OpenSSL 1.0.1a 15 Oct 2015". - -=item OPENSSL_CFLAGS - -The compiler flags set for the compilation process in the form -"compiler: ..." if available or "compiler: information not available" -otherwise. - -=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 OPENSSL_PLATFORM - -The "Configure" target of the library build in the form "platform: ..." -if available or "platform: information not available" otherwise. - -=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. - -=head1 RETURN VALUE - -The version number. - -=head1 SEE ALSO - -L<crypto(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/doc/crypto/OPENSSL_config.pod b/doc/crypto/OPENSSL_config.pod deleted file mode 100644 index eae634a8fa..0000000000 --- a/doc/crypto/OPENSSL_config.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions - -=head1 SYNOPSIS - - #include <openssl/conf.h> - - #if OPENSSL_API_COMPAT < 0x10100000L - void OPENSSL_config(const char *appname); - void OPENSSL_no_config(void); - #endif - -=head1 DESCRIPTION - -OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> and -reads from the application section B<appname>. If B<appname> is NULL then -the default section, B<openssl_conf>, will be used. -Errors are silently ignored. -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 -forget it" function. -It is however B<much> better than nothing. Applications which need finer -control over their configuration functionality should use the configuration -functions such as CONF_modules_load() directly. This function is deprecated -and its use should be avoided. -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, 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 -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. - -=head1 RETURN VALUES - -Neither OPENSSL_config() nor OPENSSL_no_config() return a value. - -=head1 SEE ALSO - -L<conf(5)>, -L<CONF_modules_load_file(3)> - -=head1 HISTORY - -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/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod deleted file mode 100644 index 60dd96484c..0000000000 --- a/doc/crypto/OPENSSL_ia32cap.pod +++ /dev/null @@ -1,139 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_ia32cap - the x86[_64] processor capabilities vector - -=head1 SYNOPSIS - - env OPENSSL_ia32cap=... <application> - -=head1 DESCRIPTION - -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 - -=item bit #4 denoting presence of Time-Stamp Counter. - -=item bit #19 denoting availability of CLFLUSH instruction; - -=item bit #20, reserved by Intel, is used to choose among RC4 code paths; - -=item bit #23 denoting MMX support; - -=item bit #24, FXSR bit, denoting availability of XMM registers; - -=item bit #25 denoting SSE support; - -=item bit #26 denoting SSE2 support; - -=item bit #28 denoting Hyperthreading, which is used to distinguish -cores with shared cache; - -=item bit #30, reserved by Intel, denotes specifically Intel CPUs; - -=item bit #33 denoting availability of PCLMULQDQ instruction; - -=item bit #41 denoting SSSE3, Supplemental SSE3, support; - -=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; - -=item bit #62 denoting availability of RDRAND instruction; - -=back - -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 - -=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. 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 - ADCX/ADOX | 2.23 | 2.10 | 3.3 - AVX512 | 2.25 | 2.11.8 | 3.6 - -=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/doc/crypto/OPENSSL_init_crypto.pod b/doc/crypto/OPENSSL_init_crypto.pod deleted file mode 100644 index 1989880752..0000000000 --- a/doc/crypto/OPENSSL_init_crypto.pod +++ /dev/null @@ -1,245 +0,0 @@ -=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 -L<atexit(3)> 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 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/doc/crypto/OPENSSL_instrument_bus.pod b/doc/crypto/OPENSSL_instrument_bus.pod deleted file mode 100644 index 1407261035..0000000000 --- a/doc/crypto/OPENSSL_instrument_bus.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memory bus - -=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); - #endif - -=head1 DESCRIPTION - -It was empirically found that timings of references to primary memory -are subject to irregular, apparently non-deterministic variations. The -subroutines in question instrument these references for purposes of -gathering entropy for random number generator. In order to make it -bus-bound a 'flush cache line' instruction is used between probes. In -addition probes are added to B<vector> elements in atomic or -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 -oscillator cycles every probe took. - -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]>, -with B<max> value of 0 meaning "as many as it takes." - -=head1 RETURN VALUE - -Return value of 0 indicates that CPU is not capable of performing the -benchmark, either because oscillator counter or 'flush cache line' is -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/doc/crypto/OPENSSL_load_builtin_modules.pod b/doc/crypto/OPENSSL_load_builtin_modules.pod deleted file mode 100644 index 112718a68a..0000000000 --- a/doc/crypto/OPENSSL_load_builtin_modules.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules - -=head1 SYNOPSIS - - #include <openssl/conf.h> - - void OPENSSL_load_builtin_modules(void); - void ASN1_add_oid_module(void); - ENGINE_add_conf_module(); - -=head1 DESCRIPTION - -The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL -configuration modules to the internal list. They can then be used by the -OpenSSL configuration code. - -ASN1_add_oid_module() adds just the ASN1 OBJECT module. - -ENGINE_add_conf_module() adds just the ENGINE configuration module. - -=head1 NOTES - -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 -configuration code. - -Applications should call OPENSSL_load_builtin_modules() to load all -configuration modules instead of adding modules selectively: otherwise -functionality may be missing from the application if an when new -modules are added. - -=head1 RETURN VALUE - -None of the functions return a value. - -=head1 SEE ALSO - -L<conf(3)>, L<OPENSSL_config(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/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod deleted file mode 100644 index 50f09751cf..0000000000 --- a/doc/crypto/OPENSSL_malloc.pod +++ /dev/null @@ -1,205 +0,0 @@ -=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. It is normally -called at startup, but can be called at any time. - -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/doc/crypto/OPENSSL_secure_malloc.pod b/doc/crypto/OPENSSL_secure_malloc.pod deleted file mode 100644 index 517bfbcde1..0000000000 --- a/doc/crypto/OPENSSL_secure_malloc.pod +++ /dev/null @@ -1,124 +0,0 @@ -=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, -CRYPTO_secure_free, OPENSSL_secure_actual_size, OPENSSL_secure_allocated, -CYRPTO_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); - - size_t OPENSSL_secure_actual_size(const void *ptr); - int OPENSSL_secure_allocated(const void *ptr); - - size_t CYRPTO_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() returns no values. - -=head1 SEE ALSO - -L<OPENSSL_malloc(3)>, -L<BN_new(3)>, -L<bn_internal(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/doc/crypto/OpenSSL_add_all_algorithms.pod b/doc/crypto/OpenSSL_add_all_algorithms.pod deleted file mode 100644 index aaa28dd6a9..0000000000 --- a/doc/crypto/OpenSSL_add_all_algorithms.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=head1 NAME - -OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup - -add algorithms to internal table - -=head1 SYNOPSIS - - #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) -# 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(). 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. - -OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and -ciphers). - -OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including -password based encryption algorithms. - -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 - -None of the functions return a value. - -=head1 NOTES - -A typical application will call OpenSSL_add_all_algorithms() initially and -EVP_cleanup() before exiting. - -An application does not need to add algorithms to use them explicitly, for example -by EVP_sha1(). It just needs to add them if it (or any of the functions it calls) -needs to lookup algorithms. - -The cipher and digest lookup functions are used in many parts of the library. If -the table is not initialized several functions will misbehave and complain they -cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries. -This is a common query in the OpenSSL mailing lists. - -Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a -statically linked executable can be quite large. If this is important it is possible -to just add the required ciphers and digests. - -=head1 BUGS - -Although the functions do not return error codes it is possible for them to fail. -This will only happen as a result of a memory allocation failure so this is not -too much of a problem in practice. - -=head1 SEE ALSO - -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/doc/crypto/PEM_read.pod b/doc/crypto/PEM_read.pod deleted file mode 100644 index 66cbc7d243..0000000000 --- a/doc/crypto/PEM_read.pod +++ /dev/null @@ -1,127 +0,0 @@ -=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/doc/crypto/PEM_read_CMS.pod b/doc/crypto/PEM_read_CMS.pod deleted file mode 100644 index 649c8089a9..0000000000 --- a/doc/crypto/PEM_read_CMS.pod +++ /dev/null @@ -1,97 +0,0 @@ -=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/doc/crypto/PEM_read_bio_PrivateKey.pod b/doc/crypto/PEM_read_bio_PrivateKey.pod deleted file mode 100644 index fbfe975be0..0000000000 --- a/doc/crypto/PEM_read_bio_PrivateKey.pod +++ /dev/null @@ -1,481 +0,0 @@ -=pod - -=head1 NAME - -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, -PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, -PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, -PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, -PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, -PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, -PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, -PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, -PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, -PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, -PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, -PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, -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 routines - -=head1 SYNOPSIS - - #include <openssl/pem.h> - - 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); - 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); - 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); - - int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, - 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); - - EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, - 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); - RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, - 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); - int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, - 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); - RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, - 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); - RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, - 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); - DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, - 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); - int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, - 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); - DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, - 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); - X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, - 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); - X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, - 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); - -=head1 DESCRIPTION - -The PEM functions read or write structures in PEM format. In -this sense PEM format is simply base64 encoded data surrounded -by header lines. - -For more details about the meaning of arguments see the -B<PEM FUNCTION ARGUMENTS> section. - -Each operation has four functions associated with it. For -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 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_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 -it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm -to use is specified in the B<nid> parameter and should be the NID of the -corresponding OBJECT IDENTIFIER (see NOTES section). - -The B<PUBKEY> functions process a public key using an EVP_PKEY -structure. The public key is encoded as a SubjectPublicKeyInfo -structure. - -The B<RSAPrivateKey> functions process an RSA private key using an -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 -RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey -structure. - -The B<RSA_PUBKEY> functions also process an RSA public key using -an RSA structure. However the public key is encoded using a -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. 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 -a DSA structure. The public key is encoded using a -SubjectPublicKeyInfo structure and an error occurs if the public -key is not DSA. - -The B<DSAparams> functions process DSA parameters using a DSA -structure. The parameters are encoded using a Dss-Parms structure -as defined in RFC2459. - -The B<DHparams> functions process DH parameters using a DH -structure. The parameters are encoded using a PKCS#3 DHparameter -structure. - -The B<X509> functions process an X509 certificate using an X509 -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. - -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> -write functions use B<CERTIFICATE REQUEST> in the header whereas -the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST> -(as required by some CAs). The B<X509_REQ> read functions will -handle either form so there are no B<X509_REQ_NEW> read functions. - -The B<X509_CRL> functions process an X509 CRL using an X509_CRL -structure. - -The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7 -structure. - -=head1 PEM FUNCTION ARGUMENTS - -The PEM functions have many common arguments. - -The B<bp> BIO parameter (if present) specifies the BIO to read from -or write to. - -The B<fp> FILE parameter (if present) specifies the FILE pointer to -read from or write to. - -The PEM read functions all take an argument B<TYPE **x> and return -a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function -uses. If B<x> is NULL then the parameter is ignored. If B<x> is not -NULL but B<*x> is NULL then the structure returned will be written -to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made -to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). -Irrespective of the value of B<x> a pointer to the structure is always -returned (or NULL if an error occurred). - -The PEM functions which write private keys take an B<enc> parameter -which specifies the encryption algorithm to use, encryption is done -at the PEM level. If this parameter is set to NULL then the private -key is written in unencrypted form. - -The B<cb> argument is the callback to use when querying for the pass -phrase used for encrypted PEM structures (normally only private keys). - -For the PEM write routines if the B<kstr> parameter is not NULL then -B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is -ignored. - -If the B<cb> parameters is set to NULL and the B<u> parameter is not -NULL then the B<u> parameter is interpreted as a null terminated string -to use as the passphrase. If both B<cb> and B<u> are NULL then the -default callback routine is used which will typically prompt for the -passphrase on the current terminal with echoing turned off. - -The default passphrase callback is sometimes inappropriate (for example -in a GUI application) so an alternative can be supplied. The callback -routine has the following form: - - int cb(char *buf, int size, int rwflag, void *u); - -B<buf> is the buffer to write the passphrase to. B<size> is the maximum -length of the passphrase (i.e. the size of buf). B<rwflag> is a flag -which is set to 0 when reading and 1 when writing. A typical routine -will ask the user to verify the passphrase (for example by prompting -for it twice) if B<rwflag> is 1. The B<u> parameter has the same -value as the B<u> parameter passed to the PEM routine. It allows -arbitrary data to be passed to the callback by the application -(for example a window handle in a GUI application). The callback -B<must> return the number of characters in the passphrase or 0 if -an error occurred. - -=head1 EXAMPLES - -Although the PEM routines take several arguments in almost all applications -most of them are set to 0 or NULL. - -Read a certificate in PEM format from a BIO: - - X509 *x; - x = PEM_read_bio_X509(bp, NULL, 0, NULL); - if (x == NULL) { - /* Error */ - } - -Alternative method: - - X509 *x = NULL; - if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { - /* Error */ - } - -Write a certificate to a BIO: - - if (!PEM_write_bio_X509(bp, x)) { - /* Error */ - } - -Write a private key (using traditional format) to a BIO using -triple DES encryption, the pass phrase is prompted for: - - if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) { - /* Error */ - } - -Write a private key (using PKCS#8 format) to a BIO using triple -DES encryption, using the pass phrase "hello": - - if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) { - /* Error */ - } - -Read a private key from a BIO using a pass phrase callback: - - key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); - if (key == NULL) { - /* Error */ - } - -Skeleton pass phrase callback: - - int pass_cb(char *buf, int size, int rwflag, void *u) - { - int len; - char *tmp; - - /* We'd probably do something else if 'rwflag' is 1 */ - printf("Enter pass phrase for \"%s\"\n", (char *)u); - - /* get pass phrase, length 'len' into 'tmp' */ - tmp = "hello"; - len = strlen(tmp); - if (len <= 0) - return 0; - - if (len > size) - len = size; - memcpy(buf, tmp, len); - return len; - } - -=head1 NOTES - -The old B<PrivateKey> write routines are retained for compatibility. -New applications should write private keys using the -PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines -because they are more secure (they use an iteration count of 2048 whereas -the traditional routines use a count of 1) unless compatibility with older -versions of OpenSSL is important. - -The B<PrivateKey> read routines can be used in all applications because -they handle all formats transparently. - -A frequent cause of problems is attempting to use the PEM routines like -this: - - X509 *x; - PEM_read_bio_X509(bp, &x, 0, NULL); - -this is a bug because an attempt will be made to reuse the data at B<x> -which is an uninitialised pointer. - -=head1 PEM ENCRYPTION FORMAT - -These old B<PrivateKey> routines use a non standard technique for encryption. - -The private key (or other data) takes the following form: - - -----BEGIN RSA PRIVATE KEY----- - Proc-Type: 4,ENCRYPTED - DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 - - ...base64 encoded data... - -----END RSA PRIVATE KEY----- - -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: - - EVP_CIPHER* cipher = EVP_des_ede3_cbc(); - EVP_MD* md = EVP_md5(); - - 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 - -The PEM read routines in some versions of OpenSSL will not correctly reuse -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: - - X509_free(x); - x = PEM_read_bio_X509(bp, NULL, 0, NULL); - -is guaranteed to work. - -=head1 RETURN CODES - -The read routines return either a pointer to the structure read or NULL -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_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/doc/crypto/PEM_write_bio_CMS_stream.pod b/doc/crypto/PEM_write_bio_CMS_stream.pod deleted file mode 100644 index c73fafd44b..0000000000 --- a/doc/crypto/PEM_write_bio_CMS_stream.pod +++ /dev/null @@ -1,50 +0,0 @@ -=pod - -=head1 NAME - -PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); - -=head1 DESCRIPTION - -PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format. - -It is otherwise identical to the function SMIME_write_CMS(). - -=head1 NOTES - -This function is effectively a version of the PEM_write_bio_CMS() supporting -streaming. - -=head1 RETURN VALUES - -PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -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/doc/crypto/PEM_write_bio_PKCS7_stream.pod b/doc/crypto/PEM_write_bio_PKCS7_stream.pod deleted file mode 100644 index 77f97aaa2b..0000000000 --- a/doc/crypto/PEM_write_bio_PKCS7_stream.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - -PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); - -=head1 DESCRIPTION - -PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format. - -It is otherwise identical to the function SMIME_write_PKCS7(). - -=head1 NOTES - -This function is effectively a version of the PEM_write_bio_PKCS7() supporting -streaming. - -=head1 RETURN VALUES - -PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -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/doc/crypto/PKCS12_create.pod b/doc/crypto/PKCS12_create.pod deleted file mode 100644 index 0a43b96c31..0000000000 --- a/doc/crypto/PKCS12_create.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -PKCS12_create - create a PKCS#12 structure - -=head1 SYNOPSIS - - #include <openssl/pkcs12.h> - - 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 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. - -B<nid_key> and B<nid_cert> are the encryption algorithms that should be used -for the key and certificate respectively. B<iter> is the encryption algorithm -iteration count to use and B<mac_iter> is the MAC iteration count to use. -B<keytype> is the type of key. - -=head1 NOTES - -The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype> -can all be set to zero and sensible defaults will be used. - -These defaults are: 40 bit RC2 encryption for certificates, triple DES -encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER -(currently 2048) and a MAC iteration count of 1. - -The default MAC iteration count is 1 in order to retain compatibility with -old software which did not interpret MAC iteration counts. If such compatibility -is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER. - -B<keytype> adds a flag to the store private key. This is a non standard extension -that is only currently interpreted by MSIE. If set to zero the flag is omitted, -if set to B<KEY_SIG> the key can be used for signing only, if set to B<KEY_EX> -it can be used for signing and encryption. This option was useful for old -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. - -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 -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. - -B<mac_iter> can be set to -1 and the MAC will then be omitted entirely. - -=head1 SEE ALSO - -L<d2i_PKCS12(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/doc/crypto/PKCS12_newpass.pod b/doc/crypto/PKCS12_newpass.pod deleted file mode 100644 index b91051195f..0000000000 --- a/doc/crypto/PKCS12_newpass.pod +++ /dev/null @@ -1,103 +0,0 @@ -=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 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/doc/crypto/PKCS12_parse.pod b/doc/crypto/PKCS12_parse.pod deleted file mode 100644 index 2dfa7e259b..0000000000 --- a/doc/crypto/PKCS12_parse.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -PKCS12_parse - parse a PKCS#12 structure - -=head1 SYNOPSIS - - #include <openssl/pkcs12.h> - -int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca); - -=head1 DESCRIPTION - -PKCS12_parse() parses a PKCS12 structure. - -B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use. -If successful the private key will be written to B<*pkey>, the corresponding -certificate to B<*cert> and any additional certificates to B<*ca>. - -=head1 NOTES - -The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in -which case additional certificates will be discarded. B<*ca> can also be a -valid STACK in which case additional certificates are appended to B<*ca>. If -B<*ca> is B<NULL> a new STACK will be allocated. - -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. - -=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)> - -=head1 BUGS - -Only a single private key and corresponding certificate is returned by this -function. More complex PKCS#12 files with multiple private keys will only -return the first match. - -Only B<friendlyName> and B<localKeyID> attributes are currently stored in -certificates. Other attributes are discarded. - -Attributes currently cannot be stored in the private key B<EVP_PKEY> structure. - -=head1 SEE ALSO - -L<d2i_PKCS12(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/doc/crypto/PKCS5_PBKDF2_HMAC.pod b/doc/crypto/PKCS5_PBKDF2_HMAC.pod deleted file mode 100644 index 5cc2caa5fb..0000000000 --- a/doc/crypto/PKCS5_PBKDF2_HMAC.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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/doc/crypto/PKCS7_decrypt.pod b/doc/crypto/PKCS7_decrypt.pod deleted file mode 100644 index 4ed8aa77fa..0000000000 --- a/doc/crypto/PKCS7_decrypt.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags); - -=head1 DESCRIPTION - -PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData -structure. B<pkey> is the private key of the recipient, B<cert> is the -recipients certificate, B<data> is a BIO to write the content to and -B<flags> is an optional set of flags. - -=head1 NOTES - -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. - -The following flags can be passed in the B<flags> parameter. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -returned. - -=head1 RETURN VALUES - -PKCS7_decrypt() returns either 1 for success or 0 for failure. -The error can be obtained from ERR_get_error(3) - -=head1 BUGS - -PKCS7_decrypt() must be passed the correct recipient key and certificate. It would -be better if it could look up the correct key and certificate from a database. - -The lack of single pass processing and need to hold all data in memory as -mentioned in PKCS7_sign() also applies to PKCS7_verify(). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<PKCS7_encrypt(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/doc/crypto/PKCS7_encrypt.pod b/doc/crypto/PKCS7_encrypt.pod deleted file mode 100644 index 4e1afc916f..0000000000 --- a/doc/crypto/PKCS7_encrypt.pod +++ /dev/null @@ -1,88 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_encrypt - create a PKCS#7 envelopedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags); - -=head1 DESCRIPTION - -PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs> -is a list of recipient certificates. B<in> is the content to be encrypted. -B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. - -=head1 NOTES - -Only RSA keys are supported in PKCS#7 and envelopedData so the recipient -certificates supplied to this function must all contain RSA public keys, though -they do not have to be signed using the RSA algorithm. - -EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use -because most clients will support it. - -Some old "export grade" clients may only support weak encryption using 40 or 64 -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. - -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 -by storing the S/MIME signed message in a memory BIO and passing it to -PKCS7_encrypt(). - -The following flags can be passed in the B<flags> parameter. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are -prepended to the data. - -Normally the supplied content is translated into MIME canonical format (as -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. If B<PKCS7_BINARY> is set then -B<PKCS7_TEXT> is ignored. - -If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output -suitable for streaming I/O: no data is read from the BIO B<in>. - -=head1 NOTES - -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 -results. - -Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), -PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_PKCS7(). - -=head1 RETURN VALUES - -PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred. -The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<PKCS7_decrypt(3)> - -=head1 HISTORY - -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/doc/crypto/PKCS7_sign.pod b/doc/crypto/PKCS7_sign.pod deleted file mode 100644 index b5a52da9a2..0000000000 --- a/doc/crypto/PKCS7_sign.pod +++ /dev/null @@ -1,124 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_sign - create a PKCS#7 signedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); - -=head1 DESCRIPTION - -PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is -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). - -The data to be signed is read from BIO B<data>. - -B<flags> is an optional set of flags. - -=head1 NOTES - -Any of the following flags (ored together) can be passed in the B<flags> -parameter. - -Many S/MIME clients expect the signed content to include valid MIME headers. If -the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended -to the data. - -If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the -PKCS7 structure, the signer's certificate must still be supplied in the -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 data being signed is included in the PKCS7 structure, unless -B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7 -detached signatures which are used in S/MIME plaintext signed messages for -example. - -Normally the supplied content is translated into MIME canonical format (as -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 -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 -the SMIMECapabilities are omitted. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of -these algorithms is disabled then it will not be included. - -If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is -just initialized ready to perform the signing operation. The signing is however -B<not> performed and the data to be signed is not read from the B<data> -parameter. Signing is deferred until after the data has been written. In this -way data can be signed in a single pass. - -If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to -which additional signers and capabilities can be added before finalization. - - -=head1 NOTES - -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 results. - -Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), -PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -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. - -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 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. - -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 -B<NOT> be NULL. - -=head1 BUGS - -Some advanced attributes such as counter signatures are not supported. - -=head1 RETURN VALUES - -PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error -occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<PKCS7_verify(3)> - -=head1 HISTORY - -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/doc/crypto/PKCS7_sign_add_signer.pod b/doc/crypto/PKCS7_sign_add_signer.pod deleted file mode 100644 index c2a06e7a77..0000000000 --- a/doc/crypto/PKCS7_sign_add_signer.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_sign_add_signer - add a signer PKCS7 signed data structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags); - - -=head1 DESCRIPTION - -PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private -key B<pkey> using message digest B<md> to a PKCS7 signed data structure -B<p7>. - -The PKCS7 structure should be obtained from an initial call to PKCS7_sign() -with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7 -signed data structure. - -If the B<md> parameter is B<NULL> then the default digest for the public -key algorithm will be used. - -Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure -is not complete and must be finalized either by streaming (if applicable) or -a call to PKCS7_final(). - - -=head1 NOTES - -The main purpose of this function is to provide finer control over a PKCS#7 -signed data structure where the simpler PKCS7_sign() function defaults are -not appropriate. For example if multiple signers or non default digest -algorithms are needed. - -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 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 -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. - -If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the -PKCS7 structure, the signer's certificate must still be supplied in the -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 -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 -the SMIMECapabilities are omitted. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of -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 -before it is finalized. - -=head1 RETURN VALUES - -PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO -structure just added or NULL if an error occurs. - -=head1 SEE ALSO - -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/doc/crypto/PKCS7_verify.pod b/doc/crypto/PKCS7_verify.pod deleted file mode 100644 index c34808eced..0000000000 --- a/doc/crypto/PKCS7_verify.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags); - - STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); - -=head1 DESCRIPTION - -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 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. - -B<flags> is an optional set of flags, which can be used to modify the verify -operation. - -PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does -B<not> check their validity or whether any signatures are valid. The B<certs> -and B<flags> parameters have the same meanings as in PKCS7_verify(). - -=head1 VERIFY PROCESS - -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>. 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 -contained in the B<p7> structure itself. If any signer's certificates cannot be -located the operation fails. - -Each signer's certificate is chain verified using the B<smimesign> purpose and -the supplied trusted certificate store. Any internal certificates in the message -are used as untrusted CAs. If any chain verify fails an error code is returned. - -Finally the signed content is read (and written to B<out> is it is not NULL) and -the signature's checked. - -If all signature's verify correctly then the function is successful. - -Any of the following flags (ored together) can be passed in the B<flags> parameter -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 -searched when locating the signer's certificate. This means that all the signers -certificates must be in the B<certs> parameter. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -returned. - -If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified. - -If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are -not used as untrusted CAs. This means that the whole verify chain (apart from -the signer's certificate) must be contained in the trusted store. - -If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked. - -=head1 NOTES - -One application of B<PKCS7_NOINTERN> is to only accept messages signed by -a small number of certificates. The acceptable certificates would be passed -in the B<certs> parameter. In this case if the signer is not one of the -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 -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. - -Chain verification should arguably be performed using the signing time rather -than the current time. However since the signing time is supplied by the -signer it cannot be trusted without additional evidence (such as a trusted -timestamp). - -=head1 RETURN VALUES - -PKCS7_verify() returns one for a successful verification and zero -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)> - -=head1 BUGS - -The trusted certificate store is not searched for the signers certificate, -this is primarily due to the inadequacies of the current B<X509_STORE> -functionality. - -The lack of single pass processing and need to hold all data in memory as -mentioned in PKCS7_sign() also applies to PKCS7_verify(). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<PKCS7_sign(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/doc/crypto/RAND_add.pod b/doc/crypto/RAND_add.pod deleted file mode 100644 index 46de165a97..0000000000 --- a/doc/crypto/RAND_add.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add -entropy to the PRNG - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - void RAND_seed(const void *buf, int num); - - void RAND_add(const void *buf, int num, double entropy); - - 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 - -RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus, -if the data at B<buf> are unpredictable to an adversary, this -increases the uncertainty about the state and makes the PRNG output -less predictable. Suitable input comes from user interaction (random -key presses, mouse movements) and certain hardware events. The -B<entropy> argument is (the lower bound of) an estimate of how much -randomness is contained in B<buf>, measured in bytes. Details about -sources of randomness and how to estimate their entropy can be found -in the literature, e.g. RFC 1750. - -RAND_add() may be called with sensitive data such as user entered -passwords. The seed values cannot be recovered from the PRNG output. - -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)> -or L<RAND_load_file(3)>. - -RAND_seed() is equivalent to RAND_add() when B<num == entropy>. - -RAND_event() and RAND_screen() are deprecated and should not be called. - -=head1 RETURN VALUES - -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)>, L<RAND_egd(3)>, -L<RAND_load_file(3)>, L<RAND_cleanup(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/doc/crypto/RAND_bytes.pod b/doc/crypto/RAND_bytes.pod deleted file mode 100644 index 684215cea3..0000000000 --- a/doc/crypto/RAND_bytes.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -RAND_bytes, RAND_pseudo_bytes - generate random data - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - 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 - -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 -unpredictable. They can be used for non-cryptographic purposes and for -certain purposes in cryptographic protocols, but usually not for key -generation etc. - -The contents of B<buf> is mixed into the entropy pool before retrieving -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)>. 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)>, L<ERR_get_error(3)>, -L<RAND_add(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/doc/crypto/RAND_cleanup.pod b/doc/crypto/RAND_cleanup.pod deleted file mode 100644 index 2640c7d2c7..0000000000 --- a/doc/crypto/RAND_cleanup.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -RAND_cleanup - erase the PRNG state - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - #if OPENSSL_API_COMPAT < 0x10100000L - void RAND_cleanup(void) - #endif - -=head1 DESCRIPTION - -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 - -RAND_cleanup() returns no value. - -=head1 SEE ALSO - -L<rand(3)> - -=head1 HISTORY - -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/doc/crypto/RAND_egd.pod b/doc/crypto/RAND_egd.pod deleted file mode 100644 index fcc57c06f9..0000000000 --- a/doc/crypto/RAND_egd.pod +++ /dev/null @@ -1,87 +0,0 @@ -=pod - -=head1 NAME - -RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - int RAND_egd(const char *path); - int RAND_egd_bytes(const char *path, int bytes); - - int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes); - -=head1 DESCRIPTION - -RAND_egd() queries the entropy gathering daemon EGD on socket B<path>. -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)> to seed the -OpenSSL built-in PRNG. -This function is more flexible than RAND_egd(). -When only one secret key must -be generated, it is not necessary to request the full amount 255 bytes from -the EGD socket. This can be advantageous, since the amount of entropy -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)>. - -=head1 NOTES - -On systems without /dev/*random devices providing entropy from the kernel, -the EGD entropy gathering daemon can be used to collect entropy. It provides -a socket interface through which entropy can be gathered in chunks up to -255 bytes. Several chunks can be queried during one connection. - -EGD is available from http://www.lothar.com/tech/crypto/ (C<perl -Makefile.PL; make; make install> to install). It is run as B<egd> -I<path>, where I<path> is an absolute path designating a socket. When -RAND_egd() is called with that path as an argument, it tries to read -random bytes that EGD has collected. RAND_egd() retrieves entropy from the -daemon using the daemon's "non-blocking read" command which shall -be answered immediately by the daemon without waiting for additional -entropy to be collected. The write and read socket operations in the -communication are blocking. - -Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is -available from -http://prngd.sourceforge.net/ . -PRNGD does employ an internal PRNG itself and can therefore never run -out of entropy. - -OpenSSL automatically queries EGD when entropy is requested via RAND_bytes() -or the status is checked via RAND_status() for the first time, if the socket -is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool. - -=head1 RETURN VALUE - -RAND_egd() and RAND_egd_bytes() return the number of bytes read from the -daemon on success, and -1 if the connection failed or the daemon did not -return enough data to fully seed the PRNG. - -RAND_query_egd_bytes() returns the number of bytes read from the daemon on -success, and -1 if the connection failed. The PRNG state is not considered. - -=head1 SEE ALSO - -L<rand(3)>, L<RAND_add(3)>, -L<RAND_cleanup(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/doc/crypto/RAND_load_file.pod b/doc/crypto/RAND_load_file.pod deleted file mode 100644 index 39084b2c5d..0000000000 --- a/doc/crypto/RAND_load_file.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - const char *RAND_file_name(char *buf, size_t num); - - int RAND_load_file(const char *filename, long max_bytes); - - int RAND_write_file(const char *filename); - -=head1 DESCRIPTION - -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. - -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 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 -file B<filename> which can be used to initialize the PRNG by calling -RAND_load_file() in a later session. - -=head1 RETURN VALUES - -RAND_load_file() returns the number of bytes read. - -RAND_write_file() returns the number of bytes written, and -1 if the -bytes written were generated without appropriate seed. - -RAND_file_name() returns a pointer to B<buf> on success, and NULL on -error. - -=head1 SEE ALSO - -L<rand(3)>, L<RAND_add(3)>, L<RAND_cleanup(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/doc/crypto/RAND_set_rand_method.pod b/doc/crypto/RAND_set_rand_method.pod deleted file mode 100644 index 02fe90ca89..0000000000 --- a/doc/crypto/RAND_set_rand_method.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - void RAND_set_rand_method(const RAND_METHOD *meth); - - const RAND_METHOD *RAND_get_rand_method(void); - - RAND_METHOD *RAND_OpenSSL(void); - -=head1 DESCRIPTION - -A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number -generation. By modifying the method, alternative implementations such as -hardware RNGs may be used. IMPORTANT: See the NOTES section for important -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_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 -is no longer recommended. - -RAND_get_default_method() returns a pointer to the current RAND_METHOD. -However, the meaningfulness of this result is dependent on whether the ENGINE -API is being used, so this function is no longer recommended. - -=head1 THE RAND_METHOD STRUCTURE - - typedef struct rand_meth_st - { - void (*seed)(const void *buf, int num); - int (*bytes)(unsigned char *buf, int num); - void (*cleanup)(void); - void (*add)(const void *buf, int num, int entropy); - int (*pseudorand)(unsigned char *buf, int num); - int (*status)(void); - } RAND_METHOD; - -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_OpenSSL() return pointers to the respective methods. - -=head1 NOTES - -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. -RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in RAND and other cryptographic -algorithms. - -=head1 SEE ALSO - -L<rand(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/doc/crypto/RC4_set_key.pod b/doc/crypto/RC4_set_key.pod deleted file mode 100644 index fe5d2d1485..0000000000 --- a/doc/crypto/RC4_set_key.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -RC4_set_key, RC4 - RC4 encryption - -=head1 SYNOPSIS - - #include <openssl/rc4.h> - - void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); - - void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, - unsigned char *outdata); - -=head1 DESCRIPTION - -This library implements the Alleged RC4 cipher, which is described for -example in I<Applied Cryptography>. It is believed to be compatible -with RC4[TM], a proprietary cipher of RSA Security Inc. - -RC4 is a stream cipher with variable key length. Typically, 128 bit -(16 byte) keys are used for strong encryption, but shorter insecure -key sizes have been widely used due to export restrictions. - -RC4 consists of a key setup phase and the actual encryption or -decryption phase. - -RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long -key at B<data>. - -RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using -B<key> and places the result at B<outdata>. Repeated RC4() calls with -the same B<key> yield a continuous key stream. - -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. - -=head1 RETURN VALUES - -RC4_set_key() and RC4() do not return values. - -=head1 NOTE - -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<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/doc/crypto/RIPEMD160_Init.pod b/doc/crypto/RIPEMD160_Init.pod deleted file mode 100644 index a372e32ca3..0000000000 --- a/doc/crypto/RIPEMD160_Init.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - -RIPEMD-160 hash function - -=head1 SYNOPSIS - - #include <openssl/ripemd.h> - - unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, - unsigned char *md); - - int RIPEMD160_Init(RIPEMD160_CTX *c); - int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, - unsigned long len); - int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); - -=head1 DESCRIPTION - -RIPEMD-160 is a cryptographic hash function with a -160 bit output. - -RIPEMD160() computes the RIPEMD-160 message digest of the B<n> -bytes at B<d> and places it in B<md> (which must have space for -RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest -is placed in a static array. - -The following functions may be used if the message is not completely -stored in memory: - -RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure. - -RIPEMD160_Update() can be called repeatedly with chunks of the message to -be hashed (B<len> bytes at B<data>). - -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>. - -=head1 RETURN VALUES - -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<EVP_DigestInit(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/doc/crypto/RSA_blinding_on.pod b/doc/crypto/RSA_blinding_on.pod deleted file mode 100644 index 33d49d3720..0000000000 --- a/doc/crypto/RSA_blinding_on.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); - - void RSA_blinding_off(RSA *rsa); - -=head1 DESCRIPTION - -RSA is vulnerable to timing attacks. In a setup where attackers can -measure the time of RSA decryption or signature operations, blinding -must be used to protect the RSA operation from that attack. - -RSA_blinding_on() turns blinding on for key B<rsa> and generates a -random blinding factor. B<ctx> is B<NULL> or a pre-allocated and -initialized B<BN_CTX>. The random number generator must be seeded -prior to calling RSA_blinding_on(). - -RSA_blinding_off() turns blinding off and frees the memory used for -the blinding factor. - -=head1 RETURN VALUES - -RSA_blinding_on() returns 1 on success, and 0 if an error occurred. - -RSA_blinding_off() returns no value. - -=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/doc/crypto/RSA_check_key.pod b/doc/crypto/RSA_check_key.pod deleted file mode 100644 index d8689f4a2b..0000000000 --- a/doc/crypto/RSA_check_key.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -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 - -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. - -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_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)>. - -=head1 NOTES - -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 -override the way key data is stored and handled, and can even provide -support for HSM keys - in which case the RSA structure may contain B<no> -key data at all! If the ENGINE in question is only being used for -acceleration or analysis purposes, then in all likelihood the RSA key data -is complete and untouched, but this can't be assumed in the general case. - -=head1 BUGS - -A method of verifying the RSA key using opaque RSA API functions might need -to be considered. Right now RSA_check_key() simply uses the RSA structure -elements directly, bypassing the RSA_METHOD table altogether (and -completely violating encapsulation and object-orientation in the process). -The best fix will probably be to introduce a "check_key()" handler to the -RSA_METHOD function table so that alternative implementations can also -provide their own verifiers. - -=head1 SEE ALSO - -L<BN_is_prime_ex(3)>, -L<ERR_get_error(3)> - -=head1 HISTORY - -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/doc/crypto/RSA_generate_key.pod b/doc/crypto/RSA_generate_key.pod deleted file mode 100644 index 3bafc6fe27..0000000000 --- a/doc/crypto/RSA_generate_key.pod +++ /dev/null @@ -1,87 +0,0 @@ -=pod - -=head1 NAME - -RSA_generate_key_ex, RSA_generate_key - generate RSA key pair - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); - -Deprecated: - - #if OPENSSL_API_COMPAT < 0x00908000L - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int, int, void *), void *cb_arg); - #endif - -=head1 DESCRIPTION - -RSA_generate_key_ex() generates a key pair and stores it in the B<RSA> -structure provided in B<rsa>. The pseudo-random number generator must -be seeded prior to calling RSA_generate_key_ex(). - -The modulus size will be of length B<bits>, and the public exponent will be -B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure. -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)> page. - -=over 4 - -=item * - -While a random prime number is generated, it is called as -described in L<BN_generate_prime(3)>. - -=item * - -When the n-th randomly generated prime is rejected as not -suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called. - -=item * - -When a random p has been found with p-1 relatively prime to B<e>, -it is called as B<BN_GENCB_call(cb, 3, 0)>. - -=back - -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 was 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>. - -The error codes can be obtained by L<ERR_get_error(3)>. - -=head1 BUGS - -B<BN_GENCB_call(cb, 2, x)> is used with two different meanings. - -RSA_generate_key() goes into an infinite loop for illegal input values. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<rand(3)>, -L<RSA_generate_key(3)>, L<BN_generate_prime(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/doc/crypto/RSA_get0_key.pod b/doc/crypto/RSA_get0_key.pod deleted file mode 100644 index 52f83e1b90..0000000000 --- a/doc/crypto/RSA_get0_key.pod +++ /dev/null @@ -1,108 +0,0 @@ -=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(). - -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 version 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/doc/crypto/RSA_meth_new.pod b/doc/crypto/RSA_meth_new.pod deleted file mode 100644 index e46b3984f6..0000000000 --- a/doc/crypto/RSA_meth_new.pod +++ /dev/null @@ -1,235 +0,0 @@ -=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 version 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/doc/crypto/RSA_new.pod b/doc/crypto/RSA_new.pod deleted file mode 100644 index 3317920741..0000000000 --- a/doc/crypto/RSA_new.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -RSA_new, RSA_free - allocate and free RSA objects - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - RSA * RSA_new(void); - - void RSA_free(RSA *rsa); - -=head1 DESCRIPTION - -RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to -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)>. Otherwise it returns -a pointer to the newly allocated structure. - -RSA_free() returns no value. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, -L<RSA_generate_key(3)>, -L<RSA_new_method(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/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/doc/crypto/RSA_padding_add_PKCS1_type_1.pod deleted file mode 100644 index 30899440ad..0000000000 --- a/doc/crypto/RSA_padding_add_PKCS1_type_1.pod +++ /dev/null @@ -1,122 +0,0 @@ -=pod - -=head1 NAME - -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_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, -RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, -RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption -padding - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - - int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - - int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, - unsigned char *f, int fl, unsigned char *p, int pl); - - int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl); - - int RSA_padding_add_SSLv23(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_SSLv23(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - - int RSA_padding_add_none(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_none(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - -=head1 DESCRIPTION - -The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, -decrypt, sign and verify functions. Normally they should not be called -from application programs. - -However, they can also be called directly to implement padding for other -asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and -RSA_padding_check_PKCS1_OAEP() may be used in an application combined -with B<RSA_NO_PADDING> in order to implement OAEP with an encoding -parameter. - -RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into -B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> -does not meet the size requirements of the encoding method. - -The following encoding methods are implemented: - -=over 4 - -=item PKCS1_type_1 - -PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures - -=item PKCS1_type_2 - -PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) - -=item PKCS1_OAEP - -PKCS #1 v2.0 EME-OAEP - -=item SSLv23 - -PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification - -=item none - -simply copy the data - -=back - -The random number generator must be seeded prior to calling -RSA_padding_add_xxx(). - -RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain -a valid encoding for a B<rsa_len> byte RSA key in the respective -encoding method and stores the recovered data of at most B<tlen> bytes -(for B<RSA_NO_PADDING>: of size B<tlen>) -at B<to>. - -For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter -of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. - -=head1 RETURN VALUES - -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)>. - -=head1 SEE ALSO - -L<RSA_public_encrypt(3)>, -L<RSA_private_decrypt(3)>, -L<RSA_sign(3)>, L<RSA_verify(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/doc/crypto/RSA_print.pod b/doc/crypto/RSA_print.pod deleted file mode 100644 index 1367478f93..0000000000 --- a/doc/crypto/RSA_print.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -RSA_print, RSA_print_fp, -DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp, -DHparams_print, DHparams_print_fp - print cryptographic parameters - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_print(BIO *bp, RSA *x, int offset); - int RSA_print_fp(FILE *fp, RSA *x, int offset); - - #include <openssl/dsa.h> - - int DSAparams_print(BIO *bp, DSA *x); - int DSAparams_print_fp(FILE *fp, DSA *x); - int DSA_print(BIO *bp, DSA *x, int offset); - int DSA_print_fp(FILE *fp, DSA *x, int offset); - - #include <openssl/dh.h> - - int DHparams_print(BIO *bp, DH *x); - int DHparams_print_fp(FILE *fp, DH *x); - -=head1 DESCRIPTION - -A human-readable hexadecimal output of the components of the RSA -key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>. - -The output lines are indented by B<offset> spaces. - -=head1 RETURN VALUES - -These functions return 1 on success, 0 on error. - -=head1 SEE ALSO - -L<BN_bn2bin(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/doc/crypto/RSA_private_encrypt.pod b/doc/crypto/RSA_private_encrypt.pod deleted file mode 100644 index 7870371936..0000000000 --- a/doc/crypto/RSA_private_encrypt.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -RSA_private_encrypt, RSA_public_decrypt - low level signature operations - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - 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); - -=head1 DESCRIPTION - -These functions handle RSA signatures at a low level. - -RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a -message digest with an algorithm identifier) using the private key -B<rsa> and stores the signature in B<to>. B<to> must point to -B<RSA_size(rsa)> bytes of memory. - -B<padding> denotes one of the following modes: - -=over 4 - -=item RSA_PKCS1_PADDING - -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)> and L<RSA_verify(3)> should be -used. - -=item RSA_NO_PADDING - -Raw RSA signature. This mode should I<only> be used to implement -cryptographically sound padding modes in the application code. -Signing user data directly with RSA is insecure. - -=back - -RSA_public_decrypt() recovers the message digest from the B<flen> -bytes long signature at B<from> using the signer's public key -B<rsa>. B<to> must point to a memory section large enough to hold the -message digest (which is smaller than B<RSA_size(rsa) - -11>). B<padding> is the padding mode that was used to sign the data. - -=head1 RETURN VALUES - -RSA_private_encrypt() returns the size of the signature (i.e., -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)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, -L<RSA_sign(3)>, L<RSA_verify(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/doc/crypto/RSA_public_encrypt.pod b/doc/crypto/RSA_public_encrypt.pod deleted file mode 100644 index 2f78c27484..0000000000 --- a/doc/crypto/RSA_public_encrypt.pod +++ /dev/null @@ -1,88 +0,0 @@ -=pod - -=head1 NAME - -RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - 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); - -=head1 DESCRIPTION - -RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a -session key) using the public key B<rsa> and stores the ciphertext in -B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory. - -B<padding> denotes one of the following modes: - -=over 4 - -=item RSA_PKCS1_PADDING - -PKCS #1 v1.5 padding. This currently is the most widely used mode. - -=item RSA_PKCS1_OAEP_PADDING - -EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty -encoding parameter. This mode is recommended for all new applications. - -=item RSA_SSLV23_PADDING - -PKCS #1 v1.5 padding with an SSL-specific modification that denotes -that the server is SSL3 capable. - -=item RSA_NO_PADDING - -Raw RSA encryption. This mode should I<only> be used to implement -cryptographically sound padding modes in the application code. -Encrypting user data directly with RSA is insecure. - -=back - -B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 -based padding modes, less than RSA_size(B<rsa>) - 41 for -RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING. -The random number generator must be seeded prior to calling -RSA_public_encrypt(). - -RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the -private key B<rsa> and stores the plaintext in B<to>. B<to> must point -to a memory section large enough to hold the decrypted data (which is -smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that -was used to encrypt the data. - -=head1 RETURN VALUES - -RSA_public_encrypt() returns the size of the encrypted data (i.e., -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)>. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<rand(3)>, -L<RSA_size(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/doc/crypto/RSA_set_method.pod b/doc/crypto/RSA_set_method.pod deleted file mode 100644 index 7e7d27cf93..0000000000 --- a/doc/crypto/RSA_set_method.pod +++ /dev/null @@ -1,180 +0,0 @@ -=pod - -=head1 NAME - -RSA_set_default_method, RSA_get_default_method, RSA_set_method, -RSA_get_method, RSA_PKCS1_OpenSSL, RSA_null_method, RSA_flags, -RSA_new_method - select RSA method - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - void RSA_set_default_method(const RSA_METHOD *meth); - - RSA_METHOD *RSA_get_default_method(void); - - int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - - RSA_METHOD *RSA_get_method(const RSA *rsa); - - RSA_METHOD *RSA_PKCS1_OpenSSL(void); - - RSA_METHOD *RSA_null_method(void); - - int RSA_flags(const RSA *rsa); - - RSA *RSA_new_method(ENGINE *engine); - -=head1 DESCRIPTION - -An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA -operations. By modifying the method, alternative implementations such as -hardware accelerators may be used. IMPORTANT: See the NOTES section for -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_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 -been set as a default for RSA, so this function is no longer recommended. - -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 -recommended. - -RSA_set_method() selects B<meth> to perform all operations using the key -B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the -previous method was supplied by an ENGINE, the handle to that ENGINE will -be released during the change. It is possible to have RSA keys that only -work with certain RSA_METHOD implementations (eg. from an ENGINE module -that supports embedded hardware-protected keys), and in such cases -attempting to change the RSA_METHOD for the key can have unexpected -results. - -RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>. -This method may or may not be supplied by an ENGINE implementation, but if -it is, the return value can only be guaranteed to be valid as long as the -RSA key itself is valid and does not have its implementation changed by -RSA_set_method(). - -RSA_flags() returns the B<flags> that are set for B<rsa>'s current -RSA_METHOD. See the BUGS section. - -RSA_new_method() allocates and initializes an RSA structure so that -B<engine> will be used for the RSA operations. If B<engine> is NULL, the -default ENGINE for RSA operations is used, and if no default ENGINE is set, -the RSA_METHOD controlled by RSA_set_default_method() is used. - -RSA_flags() returns the B<flags> that are set for B<rsa>'s current method. - -RSA_new_method() allocates and initializes an B<RSA> structure so that -B<method> will be used for the RSA operations. If B<method> is B<NULL>, -the default method is used. - -=head1 THE RSA_METHOD STRUCTURE - - typedef struct rsa_meth_st - { - /* name of the implementation */ - const char *name; - - /* encrypt */ - 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, - unsigned char *to, RSA *rsa, int padding); - - /* sign arbitrary data */ - 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, - 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); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - 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); - - /* called at RSA_free */ - 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_METHOD_FLAG_NO_CHECK - don't check pub/private match - */ - int flags; - - char *app_data; /* ?? */ - - 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); - - } RSA_METHOD; - -=head1 RETURN VALUES - -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. - -RSA_set_method() returns a pointer to the old RSA_METHOD implementation -that was replaced. However, this return value should probably be ignored -because if it was supplied by an ENGINE, the pointer could be invalidated -at any time if the ENGINE is unloaded (in fact it could be unloaded as a -result of the RSA_set_method() function releasing its handle to the -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)> if the allocation fails. Otherwise -it returns a pointer to the newly allocated structure. - -=head1 BUGS - -The behaviour of RSA_flags() is a mis-feature that is left as-is for now -to avoid creating compatibility problems. RSA functionality, such as the -encryption functions, are controlled by the B<flags> value in the RSA key -itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key -(which is what this function returns). If the flags element of an RSA key -is changed, the changes will be honoured by RSA functionality but will not -be reflected in the return value of the RSA_flags() function - in effect -RSA_flags() behaves more like an RSA_default_flags() function (which does -not currently exist). - -=head1 SEE ALSO - -L<RSA_new(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/doc/crypto/RSA_sign.pod b/doc/crypto/RSA_sign.pod deleted file mode 100644 index 64418a5653..0000000000 --- a/doc/crypto/RSA_sign.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -RSA_sign, RSA_verify - RSA signatures - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_sign(int type, const unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - - int RSA_verify(int type, const unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - -=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. -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)> for lower-level -operations. - -B<type> denotes the message digest algorithm that was used to generate -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. - -RSA_verify() verifies that the signature B<sigbuf> of size B<siglen> -matches a given message digest B<m> of size B<m_len>. B<type> denotes -the message digest algorithm that was used to generate the signature. -B<rsa> is the signer's public key. - -=head1 RETURN VALUES - -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)>. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L<ERR_get_error(3)>, -L<RSA_private_encrypt(3)>, -L<RSA_public_decrypt(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/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod deleted file mode 100644 index 16303c9f90..0000000000 --- a/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - 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 - -RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size -B<m_len> using the private key B<rsa> represented in DER using PKCS #1 -padding. It stores the signature in B<sigret> and the signature size -in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of -memory. - -B<dummy> is ignored. - -The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING(). - -RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf> -of size B<siglen> is the DER representation of a given octet string -B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's -public key. - -=head1 RETURN VALUES - -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)>. - -=head1 BUGS - -These functions serve no recognizable purpose. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, -L<rand(3)>, L<RSA_sign(3)>, -L<RSA_verify(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/doc/crypto/RSA_size.pod b/doc/crypto/RSA_size.pod deleted file mode 100644 index eb6e481361..0000000000 --- a/doc/crypto/RSA_size.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -RSA_size, RSA_bits - get RSA modulus size - -=head1 SYNOPSIS - -#include <openssl/rsa.h> - -int RSA_size(const RSA *rsa); - -int RSA_bits(const RSA *rsa); - -=head1 DESCRIPTION - -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. - -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. - -=head1 SEE ALSO - -L<BN_num_bits(3)> - -=head1 HISTORY - -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/doc/crypto/SCT_new.pod b/doc/crypto/SCT_new.pod deleted file mode 100644 index 4ee41a6d41..0000000000 --- a/doc/crypto/SCT_new.pod +++ /dev/null @@ -1,194 +0,0 @@ -=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 - -=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 - -=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. Aditionally, 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(3)>, -L<SCT_verify(3)>, -L<OBJ_nid2obj(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/doc/crypto/SCT_print.pod b/doc/crypto/SCT_print.pod deleted file mode 100644 index 88ad43ecdc..0000000000 --- a/doc/crypto/SCT_print.pod +++ /dev/null @@ -1,52 +0,0 @@ -=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/doc/crypto/SCT_validate.pod b/doc/crypto/SCT_validate.pod deleted file mode 100644 index 713bcd29d8..0000000000 --- a/doc/crypto/SCT_validate.pod +++ /dev/null @@ -1,96 +0,0 @@ -=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 - -=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, the validation status will be -SCT_VALIDATION_STATUS_INVALID. Otherwise, if all checks have passed, 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(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/doc/crypto/SHA256_Init.pod b/doc/crypto/SHA256_Init.pod deleted file mode 100644 index f3565bb2f4..0000000000 --- a/doc/crypto/SHA256_Init.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update, -SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384, -SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update, -SHA512_Final - Secure Hash Algorithm - -=head1 SYNOPSIS - - #include <openssl/sha.h> - - int SHA1_Init(SHA_CTX *c); - int SHA1_Update(SHA_CTX *c, const void *data, size_t len); - int SHA1_Final(unsigned char *md, SHA_CTX *c); - unsigned char *SHA1(const unsigned char *d, size_t n, - unsigned char *md); - - int SHA224_Init(SHA256_CTX *c); - int SHA224_Update(SHA256_CTX *c, const void *data, size_t len); - int SHA224_Final(unsigned char *md, SHA256_CTX *c); - unsigned char *SHA224(const unsigned char *d, size_t n, - unsigned char *md); - - int SHA256_Init(SHA256_CTX *c); - int SHA256_Update(SHA256_CTX *c, const void *data, size_t len); - int SHA256_Final(unsigned char *md, SHA256_CTX *c); - unsigned char *SHA256(const unsigned char *d, size_t n, - unsigned char *md); - - int SHA384_Init(SHA512_CTX *c); - int SHA384_Update(SHA512_CTX *c, const void *data, size_t len); - int SHA384_Final(unsigned char *md, SHA512_CTX *c); - unsigned char *SHA384(const unsigned char *d, size_t n, - unsigned char *md); - - int SHA512_Init(SHA512_CTX *c); - int SHA512_Update(SHA512_CTX *c, const void *data, size_t len); - int SHA512_Final(unsigned char *md, SHA512_CTX *c); - unsigned char *SHA512(const unsigned char *d, size_t n, - unsigned char *md); - -=head1 DESCRIPTION - -Applications should use the higher level functions -L<EVP_DigestInit(3)> etc. instead of calling the hash -functions directly. - -SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a -160 bit output. - -SHA1() computes the SHA-1 message digest of the B<n> -bytes at B<d> and places it in B<md> (which must have space for -SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest -is placed in a static array. Note: setting B<md> to NULL is B<not thread safe>. - -The following functions may be used if the message is not completely -stored in memory: - -SHA1_Init() initializes a B<SHA_CTX> structure. - -SHA1_Update() can be called repeatedly with chunks of the message to -be hashed (B<len> bytes at B<data>). - -SHA1_Final() places the message digest in B<md>, which must have space -for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>. - -The SHA224, SHA256, SHA384 and SHA512 families of functions operate in the -same way as for the SHA1 functions. Note that SHA224 and SHA256 use a -B<SHA256_CTX> object instead of B<SHA_CTX>. SHA384 and SHA512 use B<SHA512_CTX>. -The buffer B<md> must have space for the output from the SHA variant being used -(defined by SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH and -SHA512_DIGEST_LENGTH). Also note that, as for the SHA1() function above, the -SHA224(), SHA256(), SHA384() and SHA512() functions are not thread safe if -B<md> is NULL. - -The predecessor of SHA-1, SHA, is also implemented, but it should be -used only when backward compatibility is required. - -=head1 RETURN VALUES - -SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash -value. - -SHA1_Init(), SHA1_Update() and SHA1_Final() and equivalent SHA224, SHA256, -SHA384 and SHA512 functions return 1 for success, 0 otherwise. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS PUB 180-4 (Secure Hash -Standard), -ANSI X9.30 - -=head1 SEE ALSO - -L<EVP_DigestInit(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/doc/crypto/SMIME_read_CMS.pod b/doc/crypto/SMIME_read_CMS.pod deleted file mode 100644 index efde0bda54..0000000000 --- a/doc/crypto/SMIME_read_CMS.pod +++ /dev/null @@ -1,75 +0,0 @@ -=pod - -=head1 NAME - -SMIME_read_CMS - parse S/MIME message - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont); - -=head1 DESCRIPTION - -SMIME_read_CMS() parses a message in S/MIME format. - -B<in> is a BIO to read the message from. - -If cleartext signing is used then the content is saved in a memory bio which is -written to B<*bcont>, otherwise B<*bcont> is set to NULL. - -The parsed CMS_ContentInfo structure is returned or NULL if an -error occurred. - -=head1 NOTES - -If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can -then be passed to CMS_verify() with the B<CMS_DETACHED> flag set. - -Otherwise the type of the returned structure can be determined -using CMS_get0_type(). - -To support future functionality if B<bcont> is not NULL B<*bcont> should be -initialized to NULL. For example: - - BIO *cont = NULL; - CMS_ContentInfo *cms; - - cms = SMIME_read_CMS(in, &cont); - -=head1 BUGS - -The MIME parser used by SMIME_read_CMS() is somewhat primitive. While it will -handle most S/MIME messages more complex compound formats may not work. - -The parser assumes that the CMS_ContentInfo structure is always base64 encoded -and will not handle the case where it is in binary format or uses quoted -printable format. - -The use of a memory BIO to hold the signed content limits the size of message -which can be processed due to memory restraints: a streaming single pass option -should be available. - -=head1 RETURN VALUES - -SMIME_read_CMS() returns a valid B<CMS_ContentInfo> structure or B<NULL> -if an error occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -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 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/doc/crypto/SMIME_read_PKCS7.pod b/doc/crypto/SMIME_read_PKCS7.pod deleted file mode 100644 index 86d5cc3048..0000000000 --- a/doc/crypto/SMIME_read_PKCS7.pod +++ /dev/null @@ -1,78 +0,0 @@ -=pod - -=head1 NAME - -SMIME_read_PKCS7 - parse S/MIME message - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont); - -=head1 DESCRIPTION - -SMIME_read_PKCS7() parses a message in S/MIME format. - -B<in> is a BIO to read the message from. - -If cleartext signing is used then the content is saved in -a memory bio which is written to B<*bcont>, otherwise -B<*bcont> is set to B<NULL>. - -The parsed PKCS#7 structure is returned or B<NULL> if an -error occurred. - -=head1 NOTES - -If B<*bcont> is not B<NULL> then the message is clear text -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(). - -To support future functionality if B<bcont> is not B<NULL> -B<*bcont> should be initialized to B<NULL>. For example: - - BIO *cont = NULL; - PKCS7 *p7; - - p7 = SMIME_read_PKCS7(in, &cont); - -=head1 BUGS - -The MIME parser used by SMIME_read_PKCS7() is somewhat primitive. -While it will handle most S/MIME messages more complex compound -formats may not work. - -The parser assumes that the PKCS7 structure is always base64 -encoded and will not handle the case where it is in binary format -or uses quoted printable format. - -The use of a memory BIO to hold the signed content limits the size -of message which can be processed due to memory restraints: a -streaming single pass option should be available. - -=head1 RETURN VALUES - -SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL> -is an error occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<PKCS7_type(3)> -L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>, -L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> -L<PKCS7_decrypt(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/doc/crypto/SMIME_write_CMS.pod b/doc/crypto/SMIME_write_CMS.pod deleted file mode 100644 index d58baeb746..0000000000 --- a/doc/crypto/SMIME_write_CMS.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -SMIME_write_CMS - convert CMS structure to S/MIME format - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); - -=head1 DESCRIPTION - -SMIME_write_CMS() adds the appropriate MIME headers to a CMS -structure to produce an S/MIME message. - -B<out> is the BIO to write the data to. B<cms> is the appropriate -B<CMS_ContentInfo> structure. If streaming is enabled then the content must be -supplied in the B<data> argument. B<flags> is an optional set of flags. - -=head1 NOTES - -The following flags can be passed in the B<flags> parameter. - -If B<CMS_DETACHED> is set then cleartext signing will be used, this option only -makes sense for SignedData where B<CMS_DETACHED> is also set when CMS_sign() is -called. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to -the content, this only makes sense if B<CMS_DETACHED> is also set. - -If the B<CMS_STREAM> flag is set streaming is performed. This flag should only -be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo -creation function. - -If cleartext signing is being used and B<CMS_STREAM> not set then the data must -be read twice: once to compute the signature in CMS_sign() and once to output -the S/MIME message. - -If streaming is performed the content is output in BER format using indefinite -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 - -SMIME_write_CMS() always base64 encodes CMS structures, there should be an -option to disable this. - -=head1 RETURN VALUES - -SMIME_write_CMS() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<CMS_sign(3)>, -L<CMS_verify(3)>, L<CMS_encrypt(3)> -L<CMS_decrypt(3)> - -=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/doc/crypto/SMIME_write_PKCS7.pod b/doc/crypto/SMIME_write_PKCS7.pod deleted file mode 100644 index b57312386e..0000000000 --- a/doc/crypto/SMIME_write_PKCS7.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags); - -=head1 DESCRIPTION - -SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7 -structure to produce an S/MIME message. - -B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7> -structure. If streaming is enabled then the content must be supplied in the -B<data> argument. B<flags> is an optional set of flags. - -=head1 NOTES - -The following flags can be passed in the B<flags> parameter. - -If B<PKCS7_DETACHED> is set then cleartext signing will be used, -this option only makes sense for signedData where B<PKCS7_DETACHED> -is also set when PKCS7_sign() is also called. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> -are added to the content, this only makes sense if B<PKCS7_DETACHED> -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 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 constructed encoding except in the case of signed data with detached -content where the content is absent and DER format is used. - -=head1 BUGS - -SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there -should be an option to disable this. - -=head1 RETURN VALUES - -SMIME_write_PKCS7() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<PKCS7_sign(3)>, -L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> -L<PKCS7_decrypt(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/doc/crypto/UI_new.pod b/doc/crypto/UI_new.pod deleted file mode 100644 index 9abb697807..0000000000 --- a/doc/crypto/UI_new.pod +++ /dev/null @@ -1,186 +0,0 @@ -=pod - -=head1 NAME - -UI, UI_METHOD, -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, - 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); - int UI_dup_input_string(UI *ui, const char *prompt, int flags, - 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); - int UI_dup_verify_string(UI *ui, const char *prompt, int flags, - 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); - 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); - 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); - - char *UI_construct_prompt(UI *ui_method, - 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); - - const char *UI_get0_result(UI *ui, int i); - - int UI_process(UI *ui); - - int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); - - void UI_set_default_method(const UI_METHOD *meth); - const UI_METHOD *UI_get_default_method(void); - const UI_METHOD *UI_get_method(UI *ui); - const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); - - UI_METHOD *UI_OpenSSL(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)>), prompting can be done in any way -imaginable, be it plain text prompting, through dialog boxes or from a -cell phone. - -All the functions work through a context of the type UI. This context -contains all the information needed to prompt correctly as well as a -reference to a UI_METHOD, which is an ordered vector of functions that -carry out the actual prompting. - -The first thing to do is to create a UI with UI_new() or UI_new_method(), -then add information to it with the UI_add or UI_dup functions. Also, -user-defined random data can be passed down to the underlying method -through calls to UI_add_user_data. The default UI method doesn't care -about these data, but other methods might. Finally, use UI_process() -to actually perform the prompting and UI_get0_result() to find the result -to the prompt. - -A UI can contain more than one prompt, which are performed in the given -sequence. Each prompt gets an index number which is returned by the -UI_add and UI_dup functions, and has to be used to get the corresponding -result with UI_get0_result(). - -The functions are as follows: - -UI_new() creates a new UI using the default UI method. When done with -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_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 -sizes of the result, not counting the final NUL character. The given -information is used to prompt for information, for example a password, -and to verify a password (i.e. having the user enter it twice and check -that the same string was entered twice). UI_add_verify_string() takes -and extra argument that should be a pointer to the result buffer of the -input string that it's supposed to verify, or verification will fail. - -UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered -in a boolean way, with a single character for yes and a different character -for no. A set of characters that can be used to cancel the prompt is given -as well. The prompt itself is divided in two, one part being the -descriptive text (given through the I<prompt> argument) and one describing -the possible answers (given through the I<action_desc> argument). - -UI_add_info_string() and UI_add_error_string() add strings that are shown at -the same time as the prompt for extra information or to show an error string. -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 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 -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). - -UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(), -UI_dup_info_string() and UI_dup_error_string() are basically the same -as their UI_add counterparts, except that they make their own copies -of all strings. - -UI_construct_prompt() is a helper function that can be used to create -a prompt from two pieces of information: an description and a name. -The default constructor (if there is none provided by the method used) -creates a string "Enter I<description> for I<name>:". With the -description "pass phrase" and the file name "foo.key", that becomes -"Enter pass phrase for foo.key:". Other methods may create whatever -string and may include encodings that will be processed by the other -method functions. - -UI_add_user_data() adds a piece of memory for the method to use at any -time. The builtin UI method doesn't care about this info. Note that several -calls to this function doesn't add data, it replaces the previous blob -with the one given as argument. - -UI_get0_user_data() retrieves the data that has last been given to the -UI with UI_add_user_data(). - -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. - -UI_ctrl() adds extra control for the application author. For now, it -understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process() -print the OpenSSL error stack as part of processing the UI, and -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. - -UI_get_default_method() returns a pointer to the current default UI method. - -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 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/doc/crypto/X509V3_get_d2i.pod b/doc/crypto/X509V3_get_d2i.pod deleted file mode 100644 index ac560b21e9..0000000000 --- a/doc/crypto/X509V3_get_d2i.pod +++ /dev/null @@ -1,241 +0,0 @@ -=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/doc/crypto/X509_ALGOR_dup.pod b/doc/crypto/X509_ALGOR_dup.pod deleted file mode 100644 index 21845e975a..0000000000 --- a/doc/crypto/X509_ALGOR_dup.pod +++ /dev/null @@ -1,48 +0,0 @@ -=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/doc/crypto/X509_CRL_get0_by_serial.pod b/doc/crypto/X509_CRL_get0_by_serial.pod deleted file mode 100644 index d9d4360fe0..0000000000 --- a/doc/crypto/X509_CRL_get0_by_serial.pod +++ /dev/null @@ -1,112 +0,0 @@ -=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(), X509_CRL_get0_by_cert(), -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/doc/crypto/X509_EXTENSION_set_object.pod b/doc/crypto/X509_EXTENSION_set_object.pod deleted file mode 100644 index f3f0de636e..0000000000 --- a/doc/crypto/X509_EXTENSION_set_object.pod +++ /dev/null @@ -1,96 +0,0 @@ -=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/doc/crypto/X509_LOOKUP_hash_dir.pod b/doc/crypto/X509_LOOKUP_hash_dir.pod deleted file mode 100644 index 08fa731238..0000000000 --- a/doc/crypto/X509_LOOKUP_hash_dir.pod +++ /dev/null @@ -1,131 +0,0 @@ -=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<c_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<d2i_X509_bio(3)>, -L<X509_STORE_load_locations(3)>, -L<X609_store_add_lookup(3)>, -L<SSL_CTX_load_verify_locations(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/doc/crypto/X509_NAME_ENTRY_get_object.pod b/doc/crypto/X509_NAME_ENTRY_get_object.pod deleted file mode 100644 index 72e0f7b11d..0000000000 --- a/doc/crypto/X509_NAME_ENTRY_get_object.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data, -X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data, -X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID, -X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - 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, 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, 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 - -X509_NAME_ENTRY_get_object() retrieves the field name of B<ne> in -and B<ASN1_OBJECT> structure. - -X509_NAME_ENTRY_get_data() retrieves the field value of B<ne> in -and B<ASN1_STRING> structure. - -X509_NAME_ENTRY_set_object() sets the field name of B<ne> to B<obj>. - -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 -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 -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 - -X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(), -X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data() -are seldom used in practice because B<X509_NAME_ENTRY> structures -are almost always part of B<X509_NAME> structures and the -corresponding B<X509_NAME> functions are typically used to -create and add new entries in a single operation. - -The arguments of these functions support similar options to the similarly -named ones of the corresponding B<X509_NAME> functions such as -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 SEE ALSO - -L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>, -L<OBJ_nid2obj(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/doc/crypto/X509_NAME_add_entry_by_txt.pod b/doc/crypto/X509_NAME_add_entry_by_txt.pod deleted file mode 100644 index 27e5baf856..0000000000 --- a/doc/crypto/X509_NAME_add_entry_by_txt.pod +++ /dev/null @@ -1,123 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID, -X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - 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, 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, const unsigned char *bytes, int len, 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); - -=head1 DESCRIPTION - -X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and -X509_NAME_add_entry_by_NID() add a field whose name is defined -by a string B<field>, an object B<obj> or a NID B<nid> respectively. -The field value to be added is in B<bytes> of length B<len>. If -B<len> is -1 then the field length is calculated internally using -strlen(bytes). - -The type of field is determined by B<type> which can either be a -definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a -standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is -added to a position determined by B<loc> and B<set>. - -X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne> -to B<name>. The new entry is added to a position determined by B<loc> -and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after -the call. - -X509_NAME_delete_entry() deletes an entry from B<name> at position -B<loc>. The deleted entry is returned and must be freed up. - -=head1 NOTES - -The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8> -is strongly recommended for the B<type> parameter. This allows the -internal code to correctly determine the type of the field and to -apply length checks according to the relevant standards. This is -done using ASN1_STRING_set_by_NID(). - -If instead an ASN1 type is used no checks are performed and the -supplied data in B<bytes> is used directly. - -In X509_NAME_add_entry_by_txt() the B<field> string represents -the field name using OBJ_txt2obj(field, 0). - -The B<loc> and B<set> parameters determine where a new entry should -be added. For almost all applications B<loc> can be set to -1 and B<set> -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. - -B<set> determines how the new type is added. If it is zero a -new RDN is created. - -If B<set> is -1 or 1 it is added to the previous or next RDN -structure respectively. This will then be a multivalued RDN: -since multivalues RDNs are very seldom used B<set> is almost -always set to zero. - -=head1 EXAMPLES - -Create an B<X509_NAME> structure: - -"C=UK, O=Disorganized Organization, CN=Joe Bloggs" - - 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 */ - if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC, - "Disorganized Organization", -1, -1, 0)) - /* Error */ - if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC, - "Joe Bloggs", -1, -1, 0)) - /* Error */ - -=head1 RETURN VALUES - -X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), -X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for -success of 0 if an error occurred. - -X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY> -structure of B<NULL> if an error occurred. - -=head1 BUGS - -B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a -different algorithm to determine field types. Since this form does -not understand multicharacter types, performs no length checks and -can result in invalid field types its use is strongly discouraged. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<d2i_X509_NAME(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/doc/crypto/X509_NAME_get0_der.pod b/doc/crypto/X509_NAME_get0_der.pod deleted file mode 100644 index f91fd4d977..0000000000 --- a/doc/crypto/X509_NAME_get0_der.pod +++ /dev/null @@ -1,40 +0,0 @@ -=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/doc/crypto/X509_NAME_get_index_by_NID.pod b/doc/crypto/X509_NAME_get_index_by_NID.pod deleted file mode 100644 index 042da24697..0000000000 --- a/doc/crypto/X509_NAME_get_index_by_NID.pod +++ /dev/null @@ -1,124 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, -X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - -X509_NAME lookup and enumeration functions - -=head1 SYNOPSIS - - #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, const ASN1_OBJECT *obj, int lastpos); - - 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, const ASN1_OBJECT *obj, char *buf, int len); - -=head1 DESCRIPTION - -These functions allow an B<X509_NAME> structure to be examined. The -B<X509_NAME> structure is the same as the B<Name> type defined in -RFC2459 (and elsewhere) and used for example in certificate subject -and issuer names. - -X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve -the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos> -should initially be set to -1. If there are no more entries -1 is returned. -If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned. - -X509_NAME_entry_count() returns the total number of entries in B<name>. - -X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name> -corresponding to index B<loc>. Acceptable values for B<loc> run from -0 to (X509_NAME_entry_count(name) - 1). The value returned is an -internal pointer which must not be freed. - -X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve -the "text" from the first entry in B<name> which matches B<nid> or -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. - -=head1 NOTES - -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 multicharacter string type -like a BMPString or a UTF8String. - -For a more general solution X509_NAME_get_index_by_NID() or -X509_NAME_get_index_by_OBJ() should be used followed by -X509_NAME_get_entry() on any matching indices and then the -various B<X509_NAME_ENTRY> utility functions on the result. - -The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in -the source code header files E<lt>openssl/obj_mac.hE<gt> and/or -E<lt>openssl/objects.hE<gt>. - -Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID() -should check for the return value of -2. Alternatively the NID validity -can be determined first by checking OBJ_nid2obj(nid) is not NULL. - -=head1 EXAMPLES - -Process all entries: - - int i; - 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 */ - } - -Process all commonName entries: - - int loc; - X509_NAME_ENTRY *e; - - loc = -1; - 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 */ - } - -=head1 RETURN VALUES - -X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() -return the index of the next matching entry or -1 if not found. -X509_NAME_get_index_by_NID() can also return -2 if the supplied -NID is invalid. - -X509_NAME_entry_count() returns the total number of entries. - -X509_NAME_get_entry() returns an B<X509_NAME> pointer to the -requested entry or B<NULL> if the index is invalid. - -=head1 SEE ALSO - -L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> - -=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/doc/crypto/X509_NAME_print_ex.pod b/doc/crypto/X509_NAME_print_ex.pod deleted file mode 100644 index eba6276bee..0000000000 --- a/doc/crypto/X509_NAME_print_ex.pod +++ /dev/null @@ -1,110 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, -X509_NAME_oneline - X509_NAME printing routines - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - 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 - -X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each -line (for multiline formats) is indented by B<indent> spaces. The output format -can be extensively customised by use of the B<flags> parameter. - -X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is -written to FILE pointer B<fp>. - -X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. At most B<size> -bytes will be written. If B<buf> is B<NULL> then a buffer is dynamically allocated -and returned, otherwise B<buf> is returned. - -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. - -=head1 NOTES - -The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which -produce a non standard output form, they don't handle multi character fields and -have various quirks and inconsistencies. Their use is strongly discouraged in new -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)> 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. - -The complete set of the flags supported by X509_NAME_print_ex() is listed below. - -Several options can be ored together. - -The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>, -B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators -to use. Two distinct separators are used between distinct RelativeDistinguishedName -components and separate values in the same RDN for a multi-valued RDN. Multi-valued -RDNs are currently very rare so the second separator will hardly ever be used. - -B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC> -uses comma and plus with spaces: this is more readable that plain comma and plus. -B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses -spaced newline and plus respectively. - -If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order. - -The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>, -B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will -use the short name (e.g. CN) the long name (e.g. commonName) always -use OID numerical form (normally OIDs are only used if the field name is not -recognised) and no field name respectively. - -If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character -separating field names and values. - -If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is -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 -control how each field value is displayed. - -In addition a number options can be set for commonly used formats. - -B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it -is equivalent to: - B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS> - - -B<XN_FLAG_ONELINE> is a more readable one line format which is the same as: - B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN> - -B<XN_FLAG_MULTILINE> is a multiline format which is the same as: - B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN> - -B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally. - -=head1 SEE ALSO - -L<ASN1_STRING_print_ex(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/doc/crypto/X509_PUBKEY_new.pod b/doc/crypto/X509_PUBKEY_new.pod deleted file mode 100644 index b13310513b..0000000000 --- a/doc/crypto/X509_PUBKEY_new.pod +++ /dev/null @@ -1,120 +0,0 @@ -=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/doc/crypto/X509_SIG_get0.pod b/doc/crypto/X509_SIG_get0.pod deleted file mode 100644 index d24eadcdf9..0000000000 --- a/doc/crypto/X509_SIG_get0.pod +++ /dev/null @@ -1,36 +0,0 @@ -=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/doc/crypto/X509_STORE_CTX_get_error.pod b/doc/crypto/X509_STORE_CTX_get_error.pod deleted file mode 100644 index 105e051a1d..0000000000 --- a/doc/crypto/X509_STORE_CTX_get_error.pod +++ /dev/null @@ -1,338 +0,0 @@ -=pod - -=head1 NAME - -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> - - 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); - - const char *X509_verify_cert_error_string(long n); - -=head1 DESCRIPTION - -These functions are typically called after X509_verify_cert() has indicated -an error or in a verification callback to determine the nature of an error. - -X509_STORE_CTX_get_error() returns the error code of B<ctx>, see -the B<ERROR CODES> section for a full description of all error codes. - -X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example -it might be used in a verification callback to set an error based on additional -checks. - -X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a -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 -returned chain persists after the B<ctx> structure is freed, when it is -no longer needed it should be free up using: - - sk_X509_pop_free(chain, X509_free); - -X509_verify_cert_error_string() returns a human readable error string for -verification error B<n>. - -=head1 RETURN VALUES - -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 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 -verification error B<n>. - -=head1 ERROR CODES - -A list of error codes and messages is shown below. Some of the -error codes are defined but currently never returned: these are described as -"unused". - -=over 4 - -=item B<X509_V_OK: ok> - -the operation was successful. - -=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> - -the issuer certificate could not be found: this occurs if the issuer certificate -of an untrusted certificate cannot be found. - -=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> - -the CRL of a certificate could not be found. - -=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> - -the certificate signature could not be decrypted. This means that the actual -signature value could not be determined rather than it not matching the -expected value, this is only meaningful for RSA keys. - -=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> - -the CRL signature could not be decrypted: this means that the actual signature -value could not be determined rather than it not matching the expected value. -Unused. - -=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> - -the public key in the certificate SubjectPublicKeyInfo could not be read. - -=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> - -the signature of the certificate is invalid. - -=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> - -the signature of the certificate is invalid. - -=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> - -the certificate is not yet valid: the notBefore date is after the current time. - -=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> - -the certificate has expired: that is the notAfter date is before the current time. - -=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> - -the CRL is not yet valid. - -=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> - -the CRL has expired. - -=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> - -the certificate notBefore field contains an invalid time. - -=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> - -the certificate notAfter field contains an invalid time. - -=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> - -the CRL lastUpdate field contains an invalid time. - -=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> - -the CRL nextUpdate field contains an invalid time. - -=item B<X509_V_ERR_OUT_OF_MEM: out of memory> - -an error occurred trying to allocate memory. This should never happen. - -=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> - -the passed certificate is self signed and the same certificate cannot be found -in the list of trusted certificates. - -=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> - -the certificate chain could be built up using the untrusted certificates but -the root could not be found locally. - -=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> - -the issuer certificate of a locally looked up certificate could not be found. -This normally means the list of trusted certificates is not complete. - -=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> - -no signatures could be verified because the chain contains only one certificate -and it is not self signed. - -=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> - -the certificate chain length is greater than the supplied maximum depth. Unused. - -=item B<X509_V_ERR_CERT_REVOKED: certificate revoked> - -the certificate has been revoked. - -=item B<X509_V_ERR_INVALID_CA: invalid CA certificate> - -a CA certificate is invalid. Either it is not a CA or its extensions are not -consistent with the supplied purpose. - -=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> - -the basicConstraints path-length parameter has been exceeded. - -=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> - -the supplied certificate cannot be used for the specified purpose. - -=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> - -the root CA is not marked as trusted for the specified purpose. - -=item B<X509_V_ERR_CERT_REJECTED: certificate rejected> - -the root CA is marked to reject the specified purpose. - -=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> - -the current candidate issuer certificate was rejected because its subject name -did not match the issuer name of the current certificate. This is only set -if issuer check debugging is enabled it is used for status notification and -is B<not> in itself an error. - -=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> - -the current candidate issuer certificate was rejected because its subject key -identifier was present and did not match the authority key identifier current -certificate. This is only set if issuer check debugging is enabled it is used -for status notification and is B<not> in itself an error. - -=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> - -the current candidate issuer certificate was rejected because its issuer name -and serial number was present and did not match the authority key identifier of -the current certificate. This is only set if issuer check debugging is enabled -it is used for status notification and is B<not> in itself an error. - -=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> - -the current candidate issuer certificate was rejected because its keyUsage -extension does not permit certificate signing. This is only set if issuer check -debugging is enabled it is used for status notification and is B<not> in itself -an error. - -=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension> - -A certificate extension had an invalid value (for example an incorrect -encoding) or some value inconsistent with other extensions. - - -=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension> - -A certificate policies extension had an invalid value (for example an incorrect -encoding) or some value inconsistent with other extensions. This error only -occurs if policy processing is enabled. - -=item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> - -The verification flags were set to require and explicit policy but none was -present. - -=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> - -The only CRLs that could be found did not match the scope of the certificate. - -=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> - -Some feature of a certificate extension is not supported. Unused. - -=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> - -A name constraint violation occurred in the permitted subtrees. - -=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> - -A name constraint violation occurred in the excluded subtrees. - -=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported> - -A certificate name constraints extension included a minimum or maximum field: -this is not supported. - -=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type> - -An unsupported name constraint type was encountered. OpenSSL currently only -supports directory name, DNS name, email and URI types. - -=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax> - -The format of the name constraint is not recognised: for example an email -address format of a form not mentioned in RFC3280. This could be caused by -a garbage extension or some new feature not currently supported. - -=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> - -An error occurred when attempting to verify the CRL path. This error can only -happen if extended CRL checking is enabled. - -=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> - -an application specific error. This will never be returned unless explicitly -set by an application. - -=back - -=head1 NOTES - -The above functions should be used instead of directly referencing the fields -in the B<X509_VERIFY_CTX> structure. - -In versions of OpenSSL before 1.0 the current certificate returned by -X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should -check the return value before printing out any debugging information relating -to the current certificate. - -If an unrecognised error code is passed to X509_verify_cert_error_string() the -numerical value of the unknown code is returned in a static buffer. This is not -thread safe but will never happen unless an invalid code is passed. - -=head1 SEE ALSO - -L<X509_verify_cert(3)>, -L<X509_up_ref(3)>, -L<X509_free(3)>. - -=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/doc/crypto/X509_STORE_CTX_new.pod b/doc/crypto/X509_STORE_CTX_new.pod deleted file mode 100644 index bf587a3bd9..0000000000 --- a/doc/crypto/X509_STORE_CTX_new.pod +++ /dev/null @@ -1,188 +0,0 @@ -=pod - -=head1 NAME - -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_set_verify, -X509_STORE_CTX_get_verify - X509_STORE_CTX initialisation - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - X509_STORE_CTX *X509_STORE_CTX_new(void); - void X509_STORE_CTX_cleanup(X509_STORE_CTX *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); - - 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); - 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 *); - X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx); - void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify); - - void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify verify); - -=head1 DESCRIPTION - -These functions initialise an B<X509_STORE_CTX> structure for subsequent use -by X509_verify_cert(). - -X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure. - -X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. -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 -good for one call to X509_verify_cert(); if you want to verify a second -certificate with the same B<ctx> then you must call X509_XTORE_CTX_cleanup() -and then X509_STORE_CTX_init() again before the second call to -X509_verify_cert(). The trusted certificate store is set to B<store>, the end -entity certificate to be verified is set to B<x509> and a set of additional -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_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 verified in B<ctx> to -B<x>. - -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 -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_STORE_CTX_get0_param() retrieves an internal pointer -to the verification parameters associated with B<ctx>. - -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>. - -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(). - -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_get_verify() obtains the current verify -function being used. - -X509_STORE_set_verify() works in the same way as for X509_STORE_CTX_set_verify() -but sets the default verify function to be used by all X509_STORE_CTX objects -created for this X509_STORE. - -A verify function is defined as an X509_STORE_CTX_verify type which has the -following signature: - - int (*verify)(X509_STORE_CTX *); - -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 - -The certificates and CRLs in a context are used internally and should B<not> -be freed up until after the associated B<X509_STORE_CTX> is freed. Copies -should be made or reference counts increased instead. - -=head1 RETURN VALUES - -X509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an -error occurred. - -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_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. - -X509_STORE_CTX_get_verify() returns the current verify function in use for this -X509_STORE_CTX. - -=head1 SEE ALSO - -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 -X509_STORE_set_verify() was first added to OpenSSL 1.1.0. It was previously -available as a macro X509_STORE_set_verify_func(). This macro still exists but -simply calls this function. - -=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/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/doc/crypto/X509_STORE_CTX_set_verify_cb.pod deleted file mode 100644 index 266a4c1ecb..0000000000 --- a/doc/crypto/X509_STORE_CTX_set_verify_cb.pod +++ /dev/null @@ -1,215 +0,0 @@ -=pod - -=head1 NAME - -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, -X509_STORE_CTX_get_verify_cb, -X509_STORE_CTX_set_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, - X509_STORE_CTX_verify_cb verify_cb); - - X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx); - 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 - -X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to -B<verify_cb> overwriting any existing callback. - -The verification callback can be used to customise the operation of certificate -verification, either by overriding error conditions or logging errors for -debugging purposes. - -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 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. - -The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that -is performing the verification operation. A callback can examine this -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_verify(), 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 -all circumstances because this will allow verification to succeed no matter -what the error. This effectively removes all security from the application -because B<any> certificate (including untrusted generated ones) will be -accepted. - -=head1 NOTES - -The verification callback can be set and inherited from the parent structure -performing the operation. In some cases (such as S/MIME verification) the -B<X509_STORE_CTX> structure is created and destroyed internally and the -only way to set a custom verification callback is by inheriting it from the -associated B<X509_STORE>. - -=head1 RETURN VALUES - -X509_STORE_CTX_set_verify_cb() does not return a value. - -=head1 EXAMPLES - -Default callback operation: - - int verify_callback(int ok, X509_STORE_CTX *ctx) - { - 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; - } - -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; - } - -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); - } - -=head1 SEE ALSO - -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_get_verify(), 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/doc/crypto/X509_STORE_get0_param.pod b/doc/crypto/X509_STORE_get0_param.pod deleted file mode 100644 index 2144f2b0ae..0000000000 --- a/doc/crypto/X509_STORE_get0_param.pod +++ /dev/null @@ -1,57 +0,0 @@ -=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 version 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/doc/crypto/X509_STORE_new.pod b/doc/crypto/X509_STORE_new.pod deleted file mode 100644 index f7a5c81416..0000000000 --- a/doc/crypto/X509_STORE_new.pod +++ /dev/null @@ -1,58 +0,0 @@ -=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/doc/crypto/X509_STORE_set_verify_cb_func.pod b/doc/crypto/X509_STORE_set_verify_cb_func.pod deleted file mode 100644 index c4f48162c3..0000000000 --- a/doc/crypto/X509_STORE_set_verify_cb_func.pod +++ /dev/null @@ -1,261 +0,0 @@ -=pod - -=head1 NAME - -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 -- set verification callback - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - typedef int (*X509_STORE_CTX_verify_cb)(int ok, X509_STORE_CTX *ctx); - typedef int (*X509_STORE_CTX_verify_fn)(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, - 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 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_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 - -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 -OpenSSL 1.0.0. - -=head1 RETURN VALUES - -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)>, L<X509_STORE_CTX_get0_chain(3)>, -L<CMS_verify(3)> - -=head1 HISTORY - -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/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod deleted file mode 100644 index 2800cd441d..0000000000 --- a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod +++ /dev/null @@ -1,294 +0,0 @@ -=pod - -=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_auth_level, X509_VERIFY_PARAM_get_auth_level, 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 - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - 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 X509_VERIFY_PARAM_get_flags(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); - - 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); - - 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); - 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); - 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); - int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, - 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. - -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 -description of values the B<flags> parameter can take. - -X509_VERIFY_PARAM_get_flags() returns the flags in B<param>. - -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 -B<trust>. - -X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to -B<t>. Normally the current time is used. - -X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled -by default) and adds B<policy> to the acceptable policy set. - -X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled -by default) and sets the acceptable policy set to B<policies>. Any existing -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 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 -B<name> is NULL, or empty the list of hostnames is cleared, and -name checks are not performed on the peer certificate. If B<name> -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 -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 -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 -any name matches. - -X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject -CommonName from the peer certificate that matched one of the reference -identifiers. When wildcard matching is not disabled, or when a -reference identifier specifies a parent domain (starts with ".") -rather than a hostname, the peer name may be a wildcard name or a -sub-domain of the reference identifier respectively. The return -string is allocated by the library and is no longer valid once the -associated B<param> argument is freed. Applications must not free -the return value. - -X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to -B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise -B<emaillen> must be set to the length of B<email>. When an email address -is specified, certificate verification automatically invokes -L<X509_check_email(3)>. - -X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>. -The B<ip> argument is in binary format, in network byte-order and -B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP -address is specified, certificate verification automatically invokes -L<X509_check_ip(3)>. - -X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to -B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string: -dotted decimal quad for IPv4 and colon-separated hexadecimal for -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_purpose(), X509_VERIFY_PARAM_set_trust(), -X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(), -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_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. - -B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate -chain. - -B<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default -any unhandled critical extensions in certificates or (if checked) CRLs results -in a fatal error. If this flag is set unhandled critical extensions are -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 -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 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 -B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any -policy> and B<inhibit policy mapping> flags respectively as defined in -B<RFC3280>. Policy checking is automatically enabled if any of these flags -are set. - -If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful -a special status code is set to the verification callback. This permits it -to examine the valid policy tree and perform additional checks or simply -log it for debugging purposes. - -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> 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 -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. - -If B<X509_V_FLAG_TRUSTED_FIRST> is set, when constructing the certificate chain, -L<X509_verify_cert(3)> will search the trust store for issuer certificates before -searching the provided untrusted certificates. -As of OpenSSL 1.1.0 this option is on by default and cannot be disabled. - -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_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 NOTES - -The above functions should be used to manipulate verification parameters -instead of legacy functions which work in specific structures such as -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 -maintained. - -If CRLs checking is enable CRLs are expected to be available in the -corresponding B<X509_STORE> structure. No attempt is made to download -CRLs from the CRL distribution points extension. - -=head1 EXAMPLE - -Enable CRL checking when performing certificate verification during SSL -connections associated with an B<SSL_CTX> structure B<ctx>: - - X509_VERIFY_PARAM *param; - param = X509_VERIFY_PARAM_new(); - X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); - SSL_CTX_set1_param(ctx, param); - X509_VERIFY_PARAM_free(param); - -=head1 SEE ALSO - -L<X509_verify_cert(3)>, -L<X509_check_host(3)>, -L<X509_check_email(3)>, -L<X509_check_ip(3)> - -=head1 HISTORY - -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-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/doc/crypto/X509_check_ca.pod b/doc/crypto/X509_check_ca.pod deleted file mode 100644 index b79efb5b5a..0000000000 --- a/doc/crypto/X509_check_ca.pod +++ /dev/null @@ -1,45 +0,0 @@ -=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/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod deleted file mode 100644 index 93848152b5..0000000000 --- a/doc/crypto/X509_check_host.pod +++ /dev/null @@ -1,157 +0,0 @@ -=pod - -=head1 NAME - -X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - int X509_check_host(X509 *, const char *name, size_t namelen, - unsigned int flags, char **peername); - int X509_check_email(X509 *, const char *address, size_t addresslen, - unsigned int flags); - int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen, - unsigned int flags); - int X509_check_ip_asc(X509 *, const char *address, unsigned int flags); - -=head1 DESCRIPTION - -The certificate matching functions are used to check whether a -certificate matches a given host name, email address, or IP address. -The validity of the certificate and its trust level has to be checked by -other means. - -X509_check_host() checks if the certificate Subject Alternative -Name (SAN) or Subject CommonName (CN) matches the specified host -name, which must be encoded in the preferred name syntax described -in section 3.5 of RFC 1034. By default, wildcards are supported -and they match only in the left-most label; but they may match -part of that label with an explicit prefix or suffix. For example, -by default, the host B<name> "www.example.com" would match a -certificate with a SAN or CN value of "*.example.com", "w*.example.com" -or "*w.example.com". - -Per section 6.4.2 of RFC 6125, B<name> values representing international -domain names must be given in A-label form. The B<namelen> argument -must be the number of characters in the name string or zero in which -case the length is calculated with strlen(B<name>). When B<name> starts -with a dot (e.g ".example.com"), it will be matched by a certificate -valid for any sub-domain of B<name>, (see also -B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below). - -When the certificate is matched, and B<peername> is not NULL, a -pointer to a copy of the matching SAN or CN from the peer certificate -is stored at the address passed in B<peername>. The application -is responsible for freeing the peername via OPENSSL_free() when it -is no longer needed. - -X509_check_email() checks if the certificate matches the specified -email B<address>. Only the mailbox syntax of RFC 822 is supported, -comments are not allowed, and no attempt is made to normalize quoted -characters. The B<addresslen> argument must be the number of -characters in the address string or zero in which case the length -is calculated with strlen(B<address>). - -X509_check_ip() checks if the certificate matches a specified IPv4 or -IPv6 address. The B<address> array is in binary format, in network -byte order. The length is either 4 (IPv4) or 16 (IPv6). Only -explicitly marked addresses in the certificates are considered; IP -addresses stored in DNS names and Common Names are ignored. - -X509_check_ip_asc() is similar, except that the NUL-terminated -string B<address> is first converted to the internal representation. - -The B<flags> argument is usually 0. It can be the bitwise OR of the -flags: - -=over 4 - -=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>, - -=item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>. - -=item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>. - -=back - -The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function -to consider the subject DN even if the certificate contains at least -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 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") -to match more than one label in B<name>; this flag only applies -to B<X509_check_host>. - -If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name> -values which start with ".", that would otherwise match any sub-domain -in the peer certificate, to only match direct child sub-domains. -Thus, for instance, with this flag set a B<name> of ".example.com" -would match a peer certificate with a DNS name of "www.example.com", -but would not match a peer certificate with a DNS name of -"www.sub.example.com"; this flag only applies to B<X509_check_host>. - -=head1 RETURN VALUES - -The functions return 1 for a successful match, 0 for a failed match -and -1 for an internal error: typically a memory allocation failure -or an ASN.1 decoding error. - -All functions can also return -2 if the input is malformed. For example, -X509_check_host() returns -2 if the provided B<name> contains embedded -NULs. - -=head1 NOTES - -Applications are encouraged to use X509_VERIFY_PARAM_set1_host() -rather than explicitly calling L<X509_check_host(3)>. Host name -checks are out of scope with the DANE-EE(3) certificate usage, -and the internal checks will be suppressed as appropriate when -DANE support is added to OpenSSL. - -=head1 SEE ALSO - -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/doc/crypto/X509_check_issued.pod b/doc/crypto/X509_check_issued.pod deleted file mode 100644 index 8e4b1117ca..0000000000 --- a/doc/crypto/X509_check_issued.pod +++ /dev/null @@ -1,45 +0,0 @@ -=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/doc/crypto/X509_dup.pod b/doc/crypto/X509_dup.pod deleted file mode 100644 index 574994d00c..0000000000 --- a/doc/crypto/X509_dup.pod +++ /dev/null @@ -1,305 +0,0 @@ -=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_METHOD_free, -X509_CRL_METHOD_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/doc/crypto/X509_get0_signature.pod b/doc/crypto/X509_get0_signature.pod deleted file mode 100644 index 61a2dda981..0000000000 --- a/doc/crypto/X509_get0_signature.pod +++ /dev/null @@ -1,97 +0,0 @@ -=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/doc/crypto/X509_get0_uids.pod b/doc/crypto/X509_get0_uids.pod deleted file mode 100644 index 4eab26e23f..0000000000 --- a/doc/crypto/X509_get0_uids.pod +++ /dev/null @@ -1,57 +0,0 @@ -=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/doc/crypto/X509_get_extension_flags.pod b/doc/crypto/X509_get_extension_flags.pod deleted file mode 100644 index 92e8a6ba1f..0000000000 --- a/doc/crypto/X509_get_extension_flags.pod +++ /dev/null @@ -1,175 +0,0 @@ -=pod - -=head1 NAME - -X509_get0_subject_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); - 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_get_extended_key_usage() return 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_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-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/doc/crypto/X509_get_notBefore.pod b/doc/crypto/X509_get_notBefore.pod deleted file mode 100644 index 82502f6588..0000000000 --- a/doc/crypto/X509_get_notBefore.pod +++ /dev/null @@ -1,103 +0,0 @@ -=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 certficate. - -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/doc/crypto/X509_get_pubkey.pod b/doc/crypto/X509_get_pubkey.pod deleted file mode 100644 index 2b9a956c2d..0000000000 --- a/doc/crypto/X509_get_pubkey.pod +++ /dev/null @@ -1,87 +0,0 @@ -=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/doc/crypto/X509_get_serialNumber.pod b/doc/crypto/X509_get_serialNumber.pod deleted file mode 100644 index 2e81c62396..0000000000 --- a/doc/crypto/X509_get_serialNumber.pod +++ /dev/null @@ -1,71 +0,0 @@ -=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/doc/crypto/X509_get_subject_name.pod b/doc/crypto/X509_get_subject_name.pod deleted file mode 100644 index ce36bbf0b2..0000000000 --- a/doc/crypto/X509_get_subject_name.pod +++ /dev/null @@ -1,86 +0,0 @@ -=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/doc/crypto/X509_get_version.pod b/doc/crypto/X509_get_version.pod deleted file mode 100644 index c1826ea30d..0000000000 --- a/doc/crypto/X509_get_version.pod +++ /dev/null @@ -1,83 +0,0 @@ -=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/doc/crypto/X509_new.pod b/doc/crypto/X509_new.pod deleted file mode 100644 index 4f5349931a..0000000000 --- a/doc/crypto/X509_new.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -X509_chain_up_ref, -X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - 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 with reference count -B<1>. - -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)>. -Otherwise it returns a pointer to the newly allocated structure. - -X509_up_ref() returns 1 for success and 0 for failure. - -X509_chain_up_ref() returns a copy of the stack or B<NULL> if an error -occurred. - -=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_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/doc/crypto/X509_sign.pod b/doc/crypto/X509_sign.pod deleted file mode 100644 index 994fd43881..0000000000 --- a/doc/crypto/X509_sign.pod +++ /dev/null @@ -1,99 +0,0 @@ -=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/doc/crypto/X509_verify_cert.pod b/doc/crypto/X509_verify_cert.pod deleted file mode 100644 index 74acf8df71..0000000000 --- a/doc/crypto/X509_verify_cert.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -X509_verify_cert - discover and verify X509 certificate chain - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - int X509_verify_cert(X509_STORE_CTX *ctx); - -=head1 DESCRIPTION - -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)> manual page. - -=head1 RETURN VALUES - -If a complete chain can be built and validated this function returns 1, -otherwise it return zero, in exceptional circumstances it can also -return a negative code. - -If the function fails additional error information can be obtained by -examining B<ctx> using, for example X509_STORE_CTX_get_error(). - -=head1 NOTES - -Applications rarely call this function directly but it is used by -OpenSSL internally for certificate validation, in both the S/MIME and -SSL/TLS code. - -A negative return value from X509_verify_cert() can occur if it is invoked -incorrectly, such as with no certificate set in B<ctx>, or when it is called -twice in succession without reinitialising B<ctx> for the second call. -A negative return value can also happen due to internal resource problems or if -a retry operation is requested during internal lookups (which never happens -with standard lookup methods). -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 -functions which use B<x509_vfy.h>. - -=head1 SEE ALSO - -L<X509_STORE_CTX_get_error(3)> - -=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/doc/crypto/X509v3_get_ext_by_NID.pod b/doc/crypto/X509v3_get_ext_by_NID.pod deleted file mode 100644 index 032f71c494..0000000000 --- a/doc/crypto/X509v3_get_ext_by_NID.pod +++ /dev/null @@ -1,140 +0,0 @@ -=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/doc/crypto/bio.pod b/doc/crypto/bio.pod deleted file mode 100644 index 1e1dd02106..0000000000 --- a/doc/crypto/bio.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=for comment openssl_manual_section 7 - -=head1 NAME - -bio - Basic I/O abstraction - -=for comment generic - -=head1 SYNOPSIS - - #include <openssl/bio.h> - -=head1 DESCRIPTION - -A BIO is an I/O abstraction, it hides many of the underlying I/O -details from an application. If an application uses a BIO for its -I/O it can transparently handle SSL connections, unencrypted network -connections and file I/O. - -There are two type of BIO, a source/sink BIO and a filter BIO. - -As its name implies a source/sink BIO is a source and/or sink of data, -examples include a socket BIO and a file BIO. - -A filter BIO takes data from one BIO and passes it through to -another, or the application. The data may be left unmodified (for -example a message digest BIO) or translated (for example an -encryption BIO). The effect of a filter BIO may change according -to the I/O operation it is performing: for example an encryption -BIO will encrypt data if it is being written to and decrypt data -if it is being read from. - -BIOs can be joined together to form a chain (a single BIO is a chain -with one component). A chain normally consist of one source/sink -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)>, -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/doc/crypto/crypto.pod b/doc/crypto/crypto.pod deleted file mode 100644 index 082f8435b2..0000000000 --- a/doc/crypto/crypto.pod +++ /dev/null @@ -1,62 +0,0 @@ -=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 -algorithms used in various Internet standards. The services provided -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. - -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, cryptographic pseudo-random number generator, and -various utilities. - -=head1 NOTES - -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, 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. -In the above example B<crl> would be freed but B<rev> would not. - -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)>, 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/doc/crypto/ct.pod b/doc/crypto/ct.pod deleted file mode 100644 index bdcda98618..0000000000 --- a/doc/crypto/ct.pod +++ /dev/null @@ -1,55 +0,0 @@ -=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_verify(3)>, -L<SCT_validate(3)>, -L<CT_POLICY_EVAL_CTX(3)>, -L<SSL_CTX_set_ct_validation_callback(3)> - -=head1 HISTORY - -This library 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/doc/crypto/d2i_DHparams.pod b/doc/crypto/d2i_DHparams.pod deleted file mode 100644 index cd1c162b40..0000000000 --- a/doc/crypto/d2i_DHparams.pod +++ /dev/null @@ -1,35 +0,0 @@ -=pod - -=head1 NAME - -d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - DH *d2i_DHparams(DH **a, unsigned char **pp, long length); - int i2d_DHparams(DH *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode PKCS#3 DH parameters using the -DHparameter structure described in PKCS#3. - -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)> - -=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/doc/crypto/d2i_Netscape_RSA.pod b/doc/crypto/d2i_Netscape_RSA.pod deleted file mode 100644 index ee39bd817a..0000000000 --- a/doc/crypto/d2i_Netscape_RSA.pod +++ /dev/null @@ -1,38 +0,0 @@ -=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/doc/crypto/d2i_PKCS8PrivateKey_bio.pod b/doc/crypto/d2i_PKCS8PrivateKey_bio.pod deleted file mode 100644 index 164d93ff4f..0000000000 --- a/doc/crypto/d2i_PKCS8PrivateKey_bio.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, -i2d_PKCS8PrivateKey_bio, i2d_PKCS8PrivateKey_fp, -i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8 format private key functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); - EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - 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); - - int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - -=head1 DESCRIPTION - -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 L<PEM_read_PrivateKey(3)>. - -=head1 NOTES - -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)> for details. - -=head1 SEE ALSO - -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/doc/crypto/d2i_PrivateKey.pod b/doc/crypto/d2i_PrivateKey.pod deleted file mode 100644 index 6b12ad9eab..0000000000 --- a/doc/crypto/d2i_PrivateKey.pod +++ /dev/null @@ -1,71 +0,0 @@ -=pod - -=head1 NAME - -d2i_PrivateKey, d2i_AutoPrivateKey, i2d_PrivateKey, -d2i_PrivateKey_bio, d2i_PrivateKey_fp -- decode and encode functions for reading and saving EVP_PKEY structures - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - EVP_PKEY *d2i_PrivateKey(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); - - EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a); - EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a) - -=head1 DESCRIPTION - -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_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. - -These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>. - -=head1 NOTES - -All these functions use DER format and unencrypted keys. Applications wishing -to encrypt or decrypt private keys should use other functions such as -d2i_PKC8PrivateKey() instead. - -If the B<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey() -(i.e. an existing structure is being reused) and the key format is PKCS#8 -then B<*a> will be freed and replaced on a successful call. - -=head1 RETURN VALUES - -d2i_PrivateKey() and d2i_AutoPrivateKey() return a valid B<EVP_KEY> structure -or B<NULL> if an error occurs. The error code can be obtained by calling -L<ERR_get_error(3)>. - -i2d_PrivateKey() returns the number of bytes successfully encoded or a -negative value if an error occurs. The error code can be obtained by calling -L<ERR_get_error(3)>. - -=head1 SEE ALSO - -L<crypto(3)>, -L<d2i_PKCS8PrivateKey(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/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod deleted file mode 100644 index 06546a4875..0000000000 --- a/doc/crypto/d2i_X509.pod +++ /dev/null @@ -1,598 +0,0 @@ -=pod - -=head1 NAME - -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_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_PublicKey, -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_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 - -=for comment generic - -=head1 SYNOPSIS - - TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length); - TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); - TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); - - int i2d_TYPE(TYPE *a, unsigned char **pp); - int i2d_TYPE_fp(FILE *fp, TYPE *a); - int i2d_TYPE_bio(BIO *bp, TYPE *a); - -=head1 DESCRIPTION - -In the description here, I<TYPE> is used a placeholder -for any of the OpenSSL datatypes, such as I<X509_CRL>. - -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<*in>. If successful a -pointer to the B<TYPE> structure is returned and B<*in> 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_TYPE_fp() is similar to d2i_TYPE() except it attempts -to parse data from FILE pointer B<fp>. - -i2d_TYPE() encodes the structure pointed to by B<a> into DER format. -If B<out> is not B<NULL>, it 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. - -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_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. - -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 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 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 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 -can trap the unwary. See the B<WARNINGS> section for some common -errors. -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 be processed after it. - -The following points about the data types might be useful: - -=over - -=item B<ASN1_OBJECT> - -Represents an ASN1 OBJECT IDENTIFIER. - -=item B<DHparams> - -Represents a PKCS#3 DH parameters structure. - -=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<AlogrithmIdentifier> 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. - -=item B<X509_REQ> - -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 */ - -Attempt to decode a buffer: - - X509 *x; - unsigned char *buf, *p; - int len; - - /* Set up buf and len to point to the input buffer. */ - p = buf; - x = d2i_X509(NULL, &p, len); - if (x == NULL) - /* error */ - -Alternative technique: - - X509 *x; - unsigned char *buf, *p; - int len; - - /* Set up buf and len to point to the input buffer. */ - p = buf; - x = NULL; - - if (d2i_X509(&x, &p, len) == NULL) - /* error */ - -=head1 WARNINGS - -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); - ... - i2d_X509(x, &buf); - ... - 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 OPENSSL_malloc() -and the subsequent call to OPENSSL_free() is likely to crash. - -Another trap to avoid is misuse of the B<a> argument to d2i_TYPE(): - - X509 *x; - - if (d2i_X509(&x, &p, len) == NULL) - /* error */ - -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 -happen. - -=head1 BUGS - -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_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_TYPE(). This may be -fixed in future so code should not assume that i2d_TYPE() will -always succeed. - -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_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure -or B<NULL> if an error occurs. If the "reuse" capability has been used with -a valid structure being passed in via B<a>, then the object is not freed in -the event of error but may be in a potentially invalid or inconsistent state. - -i2d_TYPE() returns the number of bytes successfully encoded or a negative -value if an error occurs. - -i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error -occurs. - -=head1 COPYRIGHT - -Copyright 1998-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/doc/crypto/des_modes.pod b/doc/crypto/des_modes.pod deleted file mode 100644 index 5107b77c8d..0000000000 --- a/doc/crypto/des_modes.pod +++ /dev/null @@ -1,263 +0,0 @@ -=pod - -=for comment openssl_manual_section:7 - -=head1 NAME - -des_modes - the variants of DES and other crypto algorithms of OpenSSL - -=head1 DESCRIPTION - -Several crypto algorithms for OpenSSL can be used in a number of modes. Those -are used for using block ciphers in a way similar to stream ciphers, among -other things. - -=head1 OVERVIEW - -=head2 Electronic Codebook Mode (ECB) - -Normally, this is found as the function I<algorithm>_ecb_encrypt(). - -=over 2 - -=item * - -64 bits are enciphered at a time. - -=item * - -The order of the blocks can be rearranged without detection. - -=item * - -The same plaintext block always produces the same ciphertext block -(for the same key) making it vulnerable to a 'dictionary attack'. - -=item * - -An error will only affect one ciphertext block. - -=back - -=head2 Cipher Block Chaining Mode (CBC) - -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 - -=item * - -a multiple of 64 bits are enciphered at a time. - -=item * - -The CBC mode produces the same ciphertext whenever the same -plaintext is encrypted using the same key and starting variable. - -=item * - -The chaining operation makes the ciphertext blocks dependent on the -current and all preceding plaintext blocks and therefore blocks can not -be rearranged. - -=item * - -The use of different starting variables prevents the same plaintext -enciphering to the same ciphertext. - -=item * - -An error will affect the current and the following ciphertext blocks. - -=back - -=head2 Cipher Feedback Mode (CFB) - -Normally, this is found as the function I<algorithm>_cfb_encrypt(). - -=over 2 - -=item * - -a number of bits (j) <= 64 are enciphered at a time. - -=item * - -The CFB mode produces the same ciphertext whenever the same -plaintext is encrypted using the same key and starting variable. - -=item * - -The chaining operation makes the ciphertext variables dependent on the -current and all preceding variables and therefore j-bit variables are -chained together and can not be rearranged. - -=item * - -The use of different starting variables prevents the same plaintext -enciphering to the same ciphertext. - -=item * - -The strength of the CFB mode depends on the size of k (maximal if -j == k). In my implementation this is always the case. - -=item * - -Selection of a small value for j will require more cycles through -the encipherment algorithm per unit of plaintext and thus cause -greater processing overheads. - -=item * - -Only multiples of j bits can be enciphered. - -=item * - -An error will affect the current and the following ciphertext variables. - -=back - -=head2 Output Feedback Mode (OFB) - -Normally, this is found as the function I<algorithm>_ofb_encrypt(). - -=over 2 - - -=item * - -a number of bits (j) <= 64 are enciphered at a time. - -=item * - -The OFB mode produces the same ciphertext whenever the same -plaintext enciphered using the same key and starting variable. More -over, in the OFB mode the same key stream is produced when the same -key and start variable are used. Consequently, for security reasons -a specific start variable should be used only once for a given key. - -=item * - -The absence of chaining makes the OFB more vulnerable to specific attacks. - -=item * - -The use of different start variables values prevents the same -plaintext enciphering to the same ciphertext, by producing different -key streams. - -=item * - -Selection of a small value for j will require more cycles through -the encipherment algorithm per unit of plaintext and thus cause -greater processing overheads. - -=item * - -Only multiples of j bits can be enciphered. - -=item * - -OFB mode of operation does not extend ciphertext errors in the -resultant plaintext output. Every bit error in the ciphertext causes -only one bit to be in error in the deciphered plaintext. - -=item * - -OFB mode is not self-synchronizing. If the two operation of -encipherment and decipherment get out of synchronism, the system needs -to be re-initialized. - -=item * - -Each re-initialization should use a value of the start variable -different from the start variable values used before with the same -key. The reason for this is that an identical bit stream would be -produced each time from the same parameters. This would be -susceptible to a 'known plaintext' attack. - -=back - -=head2 Triple ECB Mode - -Normally, this is found as the function I<algorithm>_ecb3_encrypt(). - -=over 2 - -=item * - -Encrypt with key1, decrypt with key2 and encrypt with key3 again. - -=item * - -As for ECB encryption but increases the key length to 168 bits. -There are theoretic attacks that can be used that make the effective -key length 112 bits, but this attack also requires 2^56 blocks of -memory, not very likely, even for the NSA. - -=item * - -If both keys are the same it is equivalent to encrypting once with -just one key. - -=item * - -If the first and last key are the same, the key length is 112 bits. -There are attacks that could reduce the effective key strength -to only slightly more than 56 bits, but these require a lot of memory. - -=item * - -If all 3 keys are the same, this is effectively the same as normal -ecb mode. - -=back - -=head2 Triple CBC Mode - -Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt(). - -=over 2 - - -=item * - -Encrypt with key1, decrypt with key2 and then encrypt with key3. - -=item * - -As for CBC encryption but increases the key length to 168 bits with -the same restrictions as for triple ecb mode. - -=back - -=head1 NOTES - -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 - -=head1 SEE ALSO - -L<blowfish(3)>, L<des(3)>, L<idea(3)>, -L<rc2(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/doc/crypto/evp.pod b/doc/crypto/evp.pod deleted file mode 100644 index 31f459084d..0000000000 --- a/doc/crypto/evp.pod +++ /dev/null @@ -1,116 +0,0 @@ -=pod - -=for comment openssl_manual_section:7 - -=head1 NAME - -evp - high-level cryptographic functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - -=head1 DESCRIPTION - -The EVP library provides a high-level interface to cryptographic -functions. - -L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and L<B<EVP_Open>I<...>|EVP_OpenInit(3)> -provide public key encryption and decryption to implement digital "envelopes". - -The L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> and -L<B<EVP_DigestVerify>I<...>|EVP_DigestVerifyInit(3)> functions implement -digital signatures and Message Authentication Codes (MACs). Also see the older -L<B<EVP_Sign>I<...>|EVP_SignInit(3)> and L<B<EVP_Verify>I<...>|EVP_VerifyInit(3)> -functions. - -Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)> -functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests. - -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_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)> 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 - -=item For key agreement see L<EVP_PKEY_derive(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<EVP_DigestSignInit(3)> -functions for this purpose. - -=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<EVP_SealInit(3)> and -L<EVP_OpenInit(3)> functions. - -=back - -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). - -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. - -All the symmetric algorithms (ciphers), digests and asymmetric algorithms -(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 -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 -cleanly supported at the low level and some operations are more efficient -using the high level interface. - -=head1 SEE ALSO - -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)>, -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/doc/crypto/i2d_CMS_bio_stream.pod b/doc/crypto/i2d_CMS_bio_stream.pod deleted file mode 100644 index ece7a4800e..0000000000 --- a/doc/crypto/i2d_CMS_bio_stream.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); - -=head1 DESCRIPTION - -i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format. - -It is otherwise identical to the function SMIME_write_CMS(). - -=head1 NOTES - -This function is effectively a version of the i2d_CMS_bio() supporting -streaming. - -=head1 BUGS - -The prefix "i2d" is arguably wrong because the function outputs BER format. - -=head1 RETURN VALUES - -i2d_CMS_bio_stream() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -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/doc/crypto/i2d_PKCS7_bio_stream.pod b/doc/crypto/i2d_PKCS7_bio_stream.pod deleted file mode 100644 index b42940a83c..0000000000 --- a/doc/crypto/i2d_PKCS7_bio_stream.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -i2d_PKCS7_bio_stream - output PKCS7 structure in BER format - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); - -=head1 DESCRIPTION - -i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format. - -It is otherwise identical to the function SMIME_write_PKCS7(). - -=head1 NOTES - -This function is effectively a version of the d2i_PKCS7_bio() supporting -streaming. - -=head1 BUGS - -The prefix "i2d" is arguably wrong because the function outputs BER format. - -=head1 RETURN VALUES - -i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -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/doc/crypto/i2d_re_X509_tbs.pod b/doc/crypto/i2d_re_X509_tbs.pod deleted file mode 100644 index 672c7ab5ae..0000000000 --- a/doc/crypto/i2d_re_X509_tbs.pod +++ /dev/null @@ -1,79 +0,0 @@ -=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/doc/crypto/o2i_SCT_LIST.pod b/doc/crypto/o2i_SCT_LIST.pod deleted file mode 100644 index 82922fce15..0000000000 --- a/doc/crypto/o2i_SCT_LIST.pod +++ /dev/null @@ -1,48 +0,0 @@ -=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/doc/crypto/x509.pod b/doc/crypto/x509.pod deleted file mode 100644 index 8319b15270..0000000000 --- a/doc/crypto/x509.pod +++ /dev/null @@ -1,75 +0,0 @@ -=pod - -=for comment openssl_manual_section:7 - -=head1 NAME - -x509 - X.509 certificate handling - -=head1 SYNOPSIS - - #include <openssl/x509.h> - -=head1 DESCRIPTION - -A 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 -found in the X.509 document from ITU-T, or in RFC3280 from PKIX. -In OpenSSL, the type X509 is used to express such a certificate, and -the type X509_CRL is used to express a CRL. - -A related structure is a certificate request, defined in PKCS#10 from -RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type -X509_REQ is used to express such a certificate request. - -To handle some complex parts of a certificate, there are the types -X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express -a certificate attributes), X509_EXTENSION (to express a certificate -extension) and a few more. - -Finally, there's the supertype X509_INFO, which can contain a CRL, a -certificate and a corresponding private key. - -B<X509_>I<...>, B<d2i_X509_>I<...> and B<i2d_X509_>I<...> handle X.509 -certificates, with some exceptions, shown below. - -B<X509_CRL_>I<...>, B<d2i_X509_CRL_>I<...> and B<i2d_X509_CRL_>I<...> -handle X.509 CRLs. - -B<X509_REQ_>I<...>, B<d2i_X509_REQ_>I<...> and B<i2d_X509_REQ_>I<...> -handle PKCS#10 certificate requests. - -B<X509_NAME_>I<...> handle certificate names. - -B<X509_ATTRIBUTE_>I<...> handle certificate attributes. - -B<X509_EXTENSION_>I<...> handle certificate extensions. - -=head1 SEE ALSO - -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<crypto(3)>, -L<x509v3(3)> - -=head1 COPYRIGHT - -Copyright 2003-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 |