diff options
Diffstat (limited to 'openssl/trunk/doc/crypto')
161 files changed, 0 insertions, 15238 deletions
diff --git a/openssl/trunk/doc/crypto/ASN1_OBJECT_new.pod b/openssl/trunk/doc/crypto/ASN1_OBJECT_new.pod deleted file mode 100644 index 51679bfc..00000000 --- a/openssl/trunk/doc/crypto/ASN1_OBJECT_new.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions - -=head1 SYNOPSIS - - 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 a ASN1_OBJECT structure. - -ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>. - -=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)|ERR_get_error(3)>. -Otherwise it returns a pointer to the newly allocated structure. - -ASN1_OBJECT_free() returns no value. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)> - -=head1 HISTORY - -ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ASN1_STRING_length.pod b/openssl/trunk/doc/crypto/ASN1_STRING_length.pod deleted file mode 100644 index c4ec693f..00000000 --- a/openssl/trunk/doc/crypto/ASN1_STRING_length.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, -ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data - -ASN1_STRING utility functions - -=head1 SYNOPSIS - - int ASN1_STRING_length(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(ASN1_STRING *x); - - int ASN1_STRING_to_UTF8(unsigned char **out, 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_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_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 free using OPENSSL_free(). - -=head1 NOTES - -Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING> -structure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed -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 RETURN VALUES - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/trunk/doc/crypto/ASN1_STRING_new.pod b/openssl/trunk/doc/crypto/ASN1_STRING_new.pod deleted file mode 100644 index 5b1bbb7e..00000000 --- a/openssl/trunk/doc/crypto/ASN1_STRING_new.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free - -ASN1_STRING allocation functions - -=head1 SYNOPSIS - - 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>. - -=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)|ERR_get_error(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/ASN1_STRING_print_ex.pod b/openssl/trunk/doc/crypto/ASN1_STRING_print_ex.pod deleted file mode 100644 index d662225b..00000000 --- a/openssl/trunk/doc/crypto/ASN1_STRING_print_ex.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines. - -=head1 SYNOPSIS - - #include <openssl/asn1.h> - - int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags); - int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags); - int ASN1_STRING_print(BIO *out, ASN1_STRING *str); - - -=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 "\WXXXX" is used -using exactly four characters for the hex representation. If it is 32 bits then -"\UXXXXXXXX" 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)|X509_NAME_print_ex(3)>, -L<ASN1_tag2str(3)|ASN1_tag2str(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/ASN1_generate_nconf.pod b/openssl/trunk/doc/crypto/ASN1_generate_nconf.pod deleted file mode 100644 index ba6e3c2e..00000000 --- a/openssl/trunk/doc/crypto/ASN1_generate_nconf.pod +++ /dev/null @@ -1,253 +0,0 @@ -=pod - -=head1 NAME - -ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions - -=head1 SYNOPSIS - - ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); - ASN1_TYPE *ASN1_generate_v3(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 wherease 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: - - B<[modifier,]type[:value]> - -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 preceeded 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> - -Emcodes 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<BITSRING>, B<BITSTR> - -Emcodes 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> - -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 set bits. - -=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 more complex example using a config file to produce a -SEQUENCE consiting 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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/trunk/doc/crypto/BIO_ctrl.pod b/openssl/trunk/doc/crypto/BIO_ctrl.pod deleted file mode 100644 index 722e8b8f..00000000 --- a/openssl/trunk/doc/crypto/BIO_ctrl.pod +++ /dev/null @@ -1,128 +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> - - long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg); - long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long)); - char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg); - long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg); - - 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); - - typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); - -=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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_f_base64.pod b/openssl/trunk/doc/crypto/BIO_f_base64.pod deleted file mode 100644 index 438af3b6..00000000 --- a/openssl/trunk/doc/crypto/BIO_f_base64.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_base64 - base64 BIO filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/evp.h> - - 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 = BIO_push(b64, bio); - BIO_write(bio, message, strlen(message)); - BIO_flush(bio); - - BIO_free_all(bio); - -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 = BIO_push(b64, bio); - while((inlen = BIO_read(bio, inbuf, 512)) > 0) - BIO_write(bio_out, inbuf, inlen); - - BIO_free_all(bio); - -=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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_f_buffer.pod b/openssl/trunk/doc/crypto/BIO_f_buffer.pod deleted file mode 100644 index c9093c6a..00000000 --- a/openssl/trunk/doc/crypto/BIO_f_buffer.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_buffer - buffering BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_f_buffer(void); - - #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL) - #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0) - #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1) - #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL) - #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf) - -=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 1024. 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 - -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 - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_f_cipher.pod b/openssl/trunk/doc/crypto/BIO_f_cipher.pod deleted file mode 100644 index 02439cea..00000000 --- a/openssl/trunk/doc/crypto/BIO_f_cipher.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/evp.h> - - BIO_METHOD * BIO_f_cipher(void); - void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher, - unsigned char *key, unsigned char *iv, int enc); - 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 signalled 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 EXAMPLES - -TBA - -=head1 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_f_md.pod b/openssl/trunk/doc/crypto/BIO_f_md.pod deleted file mode 100644 index 0d24083e..00000000 --- a/openssl/trunk/doc/crypto/BIO_f_md.pod +++ /dev/null @@ -1,138 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/evp.h> - - BIO_METHOD * BIO_f_md(void); - int BIO_set_md(BIO *b,EVP_MD *md); - int BIO_get_md(BIO *b,EVP_MD **mdp); - int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp); - -=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. - -=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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_f_null.pod b/openssl/trunk/doc/crypto/BIO_f_null.pod deleted file mode 100644 index b057c184..00000000 --- a/openssl/trunk/doc/crypto/BIO_f_null.pod +++ /dev/null @@ -1,32 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_null - null filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_f_ssl.pod b/openssl/trunk/doc/crypto/BIO_f_ssl.pod deleted file mode 100644 index f0b73173..00000000 --- a/openssl/trunk/doc/crypto/BIO_f_ssl.pod +++ /dev/null @@ -1,313 +0,0 @@ -=pod - -=head1 NAME - -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 - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/ssl.h> - - BIO_METHOD *BIO_f_ssl(void); - - #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) - #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) - #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) - #define BIO_set_ssl_renegotiate_bytes(b,num) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); - #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); - #define BIO_get_num_renegotiates(b) \ - BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); - - 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); - - #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) - -=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 SGC or step up occurs. - -In OpenSSL 0.9.6 and later 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. - -=head1 RETURN VALUES - -TBA - -=head1 EXAMPLE - -This SSL/TLS client example, attempts to retrieve a page from an -SSL/TLS web server. The I/O routines are identical to those of the -unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. - - BIO *sbio, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* We would seed the PRNG here if the platform didn't - * do it automatically - */ - - ctx = SSL_CTX_new(SSLv23_client_method()); - - /* We'd normally set some stuff like the verify paths and - * mode here because as things stand this will connect to - * any server whose certificate is signed by any CA. - */ - - sbio = BIO_new_ssl_connect(ctx); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* We might want to do other things with ssl here */ - - BIO_set_conn_hostname(sbio, "localhost:https"); - - out = BIO_new_fp(stdout, BIO_NOCLOSE); - if(BIO_do_connect(sbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error establishing SSL connection\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - /* 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; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* Might seed PRNG here */ - - ctx = SSL_CTX_new(SSLv23_server_method()); - - if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_check_private_key(ctx)) { - - fprintf(stderr, "Error setting up SSL_CTX\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* Might do other things here like setting verify locations and - * DH and/or RSA temporary key callbacks - */ - - /* New SSL BIO setup as server */ - sbio=BIO_new_ssl(ctx,0); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* Create the buffering BIO */ - - bbio = BIO_new(BIO_f_buffer()); - - /* Add to chain */ - sbio = BIO_push(bbio, sbio); - - acpt=BIO_new_accept("4433"); - - /* 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); - return 0; - } - - /* Now wait for incoming connection */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error in connection\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* We only want one connection so remove and free - * accept BIO - */ - - sbio = BIO_pop(acpt); - - BIO_free_all(acpt); - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error in SSL handshake\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - 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"); - - /* Since there is a buffering BIO present we had better flush it */ - BIO_flush(sbio); - - BIO_free_all(sbio); - -=head1 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_find_type.pod b/openssl/trunk/doc/crypto/BIO_find_type.pod deleted file mode 100644 index bd3b2561..00000000 --- a/openssl/trunk/doc/crypto/BIO_find_type.pod +++ /dev/null @@ -1,98 +0,0 @@ -=pod - -=head1 NAME - -BIO_find_type, BIO_next - BIO chain traversal - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO * BIO_find_type(BIO *b,int bio_type); - BIO * BIO_next(BIO *b); - - #define BIO_method_type(b) ((b)->method->type) - - #define BIO_TYPE_NONE 0 - #define BIO_TYPE_MEM (1|0x0400) - #define BIO_TYPE_FILE (2|0x0400) - - #define BIO_TYPE_FD (4|0x0400|0x0100) - #define BIO_TYPE_SOCKET (5|0x0400|0x0100) - #define BIO_TYPE_NULL (6|0x0400) - #define BIO_TYPE_SSL (7|0x0200) - #define BIO_TYPE_MD (8|0x0200) - #define BIO_TYPE_BUFFER (9|0x0200) - #define BIO_TYPE_CIPHER (10|0x0200) - #define BIO_TYPE_BASE64 (11|0x0200) - #define BIO_TYPE_CONNECT (12|0x0400|0x0100) - #define BIO_TYPE_ACCEPT (13|0x0400|0x0100) - #define BIO_TYPE_PROXY_CLIENT (14|0x0200) - #define BIO_TYPE_PROXY_SERVER (15|0x0200) - #define BIO_TYPE_NBIO_TEST (16|0x0200) - #define BIO_TYPE_NULL_FILTER (17|0x0200) - #define BIO_TYPE_BER (18|0x0200) - #define BIO_TYPE_BIO (19|0x0400) - - #define BIO_TYPE_DESCRIPTOR 0x0100 - #define BIO_TYPE_FILTER 0x0200 - #define BIO_TYPE_SOURCE_SINK 0x0400 - -=head1 DESCRIPTION - -The BIO_find_type() searches for a BIO of a given type in a chain, starting -at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search -is made for a BIO of that type. If B<type> is a general type (such as -B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is -searched for. BIO_find_type() returns the next matching BIO or NULL if none is -found. - -Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations. - -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 NOTES - -BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO -chain or find multiple matches using BIO_find_type(). Previous versions had to -use: - - next = bio->next_bio; - -=head1 BUGS - -BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a -NULL pointer for the B<b> argument. - -=head1 EXAMPLE - -Traverse a chain looking for digest BIOs: - - BIO *btmp; - btmp = in_bio; /* in_bio is chain to search through */ - - 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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_new.pod b/openssl/trunk/doc/crypto/BIO_new.pod deleted file mode 100644 index 2a245fc8..00000000 --- a/openssl/trunk/doc/crypto/BIO_new.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO * BIO_new(BIO_METHOD *type); - int BIO_set(BIO *a,BIO_METHOD *type); - int BIO_free(BIO *a); - void BIO_vfree(BIO *a); - void BIO_free_all(BIO *a); - -=head1 DESCRIPTION - -The BIO_new() function returns a new BIO using method B<type>. - -BIO_set() sets the method of an already existing BIO. - -BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO -but it does not return a value. Calling BIO_free() may also have some effect -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. - -=head1 RETURN VALUES - -BIO_new() returns a newly created BIO or NULL if the call fails. - -BIO_set(), BIO_free() return 1 for success and 0 for failure. - -BIO_free_all() and BIO_vfree() do not return values. - -=head1 NOTES - -Some BIOs (such as memory BIOs) can be used immediately after calling -BIO_new(). Others (such as file BIOs) need some additional initialization, -and frequently a utility function exists to create and initialize such BIOs. - -If BIO_free() is called on a BIO chain it will only free one BIO resulting -in a memory leak. - -Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() -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 - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_push.pod b/openssl/trunk/doc/crypto/BIO_push.pod deleted file mode 100644 index 8af1d3c0..00000000 --- a/openssl/trunk/doc/crypto/BIO_push.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BIO_push, BIO_pop - 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); - -=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. - -=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-chain>. 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 - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_read.pod b/openssl/trunk/doc/crypto/BIO_read.pod deleted file mode 100644 index b3452810..00000000 --- a/openssl/trunk/doc/crypto/BIO_read.pod +++ /dev/null @@ -1,66 +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>. 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. - -BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. - -BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b> - -=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. - -=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)|BIO_should_retry(3)> for details of how to -determine the cause of a retry and other I/O issues. - -If the BIO_gets() function is not supported by a BIO then it possible to -work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> -to the chain. - -=head1 SEE ALSO - -L<BIO_should_retry(3)|BIO_should_retry(3)> - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_s_accept.pod b/openssl/trunk/doc/crypto/BIO_s_accept.pod deleted file mode 100644 index 7b63e462..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_accept.pod +++ /dev/null @@ -1,195 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, -BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, -BIO_get_bind_mode, BIO_do_accept - accept BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD *BIO_s_accept(void); - - long BIO_set_accept_port(BIO *b, char *name); - 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, long dummy); - - #define BIO_BIND_NORMAL 0 - #define BIO_BIND_REUSEADDR_IF_UNUSED 1 - #define BIO_BIND_REUSEADDR 2 - - 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 a accept BIO will close any active -connection and reset the BIO into a state where it awaits another -incoming connection. - -BIO_get_fd() and BIO_set_fd() can be called to retrieve or set -the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> - -BIO_set_accept_port() uses the string B<name> to set the accept -port. The port is represented as a string of the form "host:port", -where "host" is the interface to use and "port" is the port. -Either or both values can be "*" which is interpreted as meaning -any interface or port respectively. "port" has the same syntax -as the port specified in BIO_set_conn_port() for connect BIOs, -that is it can be a numerical port string or a string to lookup -using getservbyname() and a string table. - -BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into -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 BIO_BIND_NORMAL (the default) is set -then another socket cannot be bound to the same port. If -BIO_BIND_REUSEADDR is set then other sockets can bind to the -same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and -attempt is first made to use BIO_BIN_NORMAL, if this fails -and the port is not in use then a second attempt is made -using BIO_BIND_REUSEADDR. - -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_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), -BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and -BIO_do_accept() are macros. - -=head1 RETURN VALUES - -TBA - -=head1 EXAMPLE - -This example accepts two connections on port 4444, sends messages -down each and finally closes both down. - - BIO *abio, *cbio, *cbio2; - ERR_load_crypto_strings(); - abio = BIO_new_accept("4444"); - - /* First call to BIO_accept() sets up accept BIO */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error setting up accept\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - - /* Wait for incoming connection */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - fprintf(stderr, "Connection 1 established\n"); - /* Retrieve BIO for connection */ - cbio = BIO_pop(abio); - BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); - fprintf(stderr, "Sent out data on connection 1\n"); - /* Wait for another connection */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - 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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_s_bio.pod b/openssl/trunk/doc/crypto/BIO_s_bio.pod deleted file mode 100644 index 8d0a55a0..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_bio.pod +++ /dev/null @@ -1,182 +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> - - BIO_METHOD *BIO_s_bio(void); - - #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) - #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) - - #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) - - #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) - #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) - - int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - - #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) - size_t BIO_ctrl_get_write_guarantee(BIO *b); - - #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) - 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! - -=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(); - ... - - application | TLS-engine - | | - +----------> SSL_operations() - | /\ || - | || \/ - | BIO-pair (internal_bio) - +----------< BIO-pair (network_bio) - | | - 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 transfered to the network. Use BIO_ctrl_get_read_request() to -find out, how many bytes must be written into the buffer before the -SSL_operation() can successfully be continued. - -=head1 WARNING - -As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ -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)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/BIO_s_connect.pod b/openssl/trunk/doc/crypto/BIO_s_connect.pod deleted file mode 100644 index bcf7d8dc..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_connect.pod +++ /dev/null @@ -1,192 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port, -BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, -BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, -BIO_set_nbio, BIO_do_connect - connect BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_connect(void); - - BIO *BIO_new_connect(char *name); - - long BIO_set_conn_hostname(BIO *b, char *name); - long BIO_set_conn_port(BIO *b, char *port); - long BIO_set_conn_ip(BIO *b, char *ip); - long BIO_set_conn_int_port(BIO *b, char *port); - char *BIO_get_conn_hostname(BIO *b); - char *BIO_get_conn_port(BIO *b); - char *BIO_get_conn_ip(BIO *b, dummy); - long BIO_get_conn_int_port(BIO *b, int port); - - 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. The hostname can also include the -port in the form hostname:port . It is also acceptable to use the -form "hostname/any/other/path" or "hostname:port/any/other/path". - -BIO_set_conn_port() sets the port to B<port>. B<port> can be the -numerical form or a string such as "http". A string will be looked -up first using getservbyname() on the host platform but if that -fails a standard table of port names will be used. Currently the -list is http, telnet, socks, https, ssl, ftp, gopher and wais. - -BIO_set_conn_ip() sets the IP address to B<ip> using binary form, -that is four bytes specifying the IP address in big-endian form. - -BIO_set_conn_int_port() sets the port using B<port>. B<port> should -be of type (int *). - -BIO_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. - -BIO_get_conn_ip() returns the IP address in binary form. - -BIO_get_conn_int_port() returns the port as an int. - -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]; - ERR_load_crypto_strings(); - cbio = BIO_new_connect("localhost:http"); - out = BIO_new_fp(stdout, BIO_NOCLOSE); - if(BIO_do_connect(cbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - 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 - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_s_fd.pod b/openssl/trunk/doc/crypto/BIO_s_fd.pod deleted file mode 100644 index b1de1d10..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_fd.pod +++ /dev/null @@ -1,89 +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> - - BIO_METHOD * BIO_s_fd(void); - - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) - - 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 then close() is called on the underlying -file descriptor when the BIO is freed. - -BIO_reset() attempts to change the file pointer to the start of file -using lseek(fd, 0, 0). - -BIO_seek() sets the file pointer to position B<ofs> from start of file -using lseek(fd, ofs, 0). - -BIO_tell() returns the current file position by calling lseek(fd, 0, 1). - -BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close -flag to B<c>. - -BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also -returns the file descriptor. If B<c> is not NULL it should be of type -(int *). - -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)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)> -manual pages. - -File descriptor BIOs should not be used for socket I/O. Use socket BIOs -instead. - -=head1 RETURN VALUES - -BIO_s_fd() returns the file descriptor BIO method. - -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the file descriptor or -1 if the BIO has not -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)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/openssl/trunk/doc/crypto/BIO_s_file.pod b/openssl/trunk/doc/crypto/BIO_s_file.pod deleted file mode 100644 index b2a29263..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_file.pod +++ /dev/null @@ -1,144 +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> - - 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. - -=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)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>, -L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/openssl/trunk/doc/crypto/BIO_s_mem.pod b/openssl/trunk/doc/crypto/BIO_s_mem.pod deleted file mode 100644 index 19648acf..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_mem.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -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> - - BIO_METHOD * BIO_s_mem(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(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. - -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. On a -read only BIO it restores the BIO to its original state and the read only -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 null 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 lots 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. - -=head1 BUGS - -There should be an option to set the maximum size of a memory BIO. - -There should be a way to "rewind" a read write BIO without destroying -its contents. - -The copying operation should not occur after every small read of a large BIO -to improve efficiency. - -=head1 EXAMPLE - -Create a memory BIO and write some data to it: - - BIO *mem = BIO_new(BIO_s_mem()); - BIO_puts(mem, "Hello World\n"); - -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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_s_null.pod b/openssl/trunk/doc/crypto/BIO_s_null.pod deleted file mode 100644 index e5514f72..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_null.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_null - null data sink - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_s_socket.pod b/openssl/trunk/doc/crypto/BIO_s_socket.pod deleted file mode 100644 index 1c8d3a91..00000000 --- a/openssl/trunk/doc/crypto/BIO_s_socket.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_socket, BIO_new_socket - socket BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD *BIO_s_socket(void); - - long BIO_set_fd(BIO *b, int fd, long close_flag); - long BIO_get_fd(BIO *b, int *c); - - 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_set_fd() sets the socket of BIO B<b> to B<fd> and the close -flag to B<close_flag>. - -BIO_get_fd() places the socket in B<c> if it is not NULL, it also -returns the socket. If B<c> is not NULL it should be of type (int *). - -BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>. - -=head1 NOTES - -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. - -BIO_set_fd() and BIO_get_fd() are macros. - -=head1 RETURN VALUES - -BIO_s_socket() returns the socket BIO method. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the socket or -1 if the BIO has not been -initialized. - -BIO_new_socket() returns the newly allocated BIO or NULL is an error -occurred. - -=head1 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_set_callback.pod b/openssl/trunk/doc/crypto/BIO_set_callback.pod deleted file mode 100644 index 9b6961ca..00000000 --- a/openssl/trunk/doc/crypto/BIO_set_callback.pod +++ /dev/null @@ -1,108 +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> - - #define BIO_set_callback(b,cb) ((b)->callback=(cb)) - #define BIO_get_callback(b) ((b)->callback) - #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) - #define BIO_get_callback_arg(b) ((b)->cb_arg) - - long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, - long argl,long ret); - - typedef long callback(BIO *b, int oper, const char *argp, - int argi, long argl, long retvalue); - -=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 if is interpreted as a BIO to send the information -to, otherwise stderr is used. - -callback() is the callback function itself. The meaning of each -argument is described below. - -The BIO the callback is attached to is passed in B<b>. - -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. - -The meaning of the arguments B<argp>, B<argi> and B<argl> depends on -the value of B<oper>, that is the operation being performed. - -B<retvalue> is the return value that would be returned to the -application if no callback were present. The actual value returned -is the return value of the callback itself. In the case of callbacks -called before the actual BIO operation 1 is placed in retvalue, if -the return value is not positive it will be immediately returned to -the application and the BIO operation will not be performed. - -The callback should normally simply return B<retvalue> when it has -finished processing, unless if specifically wishes to modify the -value returned to the application. - -=head1 CALLBACK OPERATIONS - -=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 SEE ALSO - -TBA diff --git a/openssl/trunk/doc/crypto/BIO_should_retry.pod b/openssl/trunk/doc/crypto/BIO_should_retry.pod deleted file mode 100644 index 539c3912..00000000 --- a/openssl/trunk/doc/crypto/BIO_should_retry.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -BIO_should_retry, BIO_should_read, BIO_should_write, -BIO_should_io_special, BIO_retry_type, BIO_should_retry, -BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) - #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) - #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) - #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) - #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) - - #define BIO_FLAGS_READ 0x01 - #define BIO_FLAGS_WRITE 0x02 - #define BIO_FLAGS_IO_SPECIAL 0x04 - #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) - #define BIO_FLAGS_SHOULD_RETRY 0x08 - - BIO * BIO_get_retry_BIO(BIO *bio, int *reason); - int BIO_get_retry_reason(BIO *bio); - -=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_get_retry_reason() 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(). - -=head1 NOTES - -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 - -TBA diff --git a/openssl/trunk/doc/crypto/BN_BLINDING_new.pod b/openssl/trunk/doc/crypto/BN_BLINDING_new.pod deleted file mode 100644 index 7b087f72..00000000 --- a/openssl/trunk/doc/crypto/BN_BLINDING_new.pod +++ /dev/null @@ -1,109 +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_get_thread_id, BN_BLINDING_set_thread_id, 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); - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); - void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); - BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, - const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, - int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), - BN_MONT_CTX *m_ctx); - -=head1 DESCRIPTION - -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. - -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 amoung -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_set_thread_id() and BN_BLINDING_get_thread_id() -set and get the "thread id" value of the B<BN_BLINDING> structure, -a field provided to users of B<BN_BLINDING> structure to help them -provide proper locking if needed for multi-threaded use. The -"thread id" of a newly allocated B<BN_BLINDING> structure is zero. - -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 occured. - -BN_BLINDING_get_thread_id() returns the thread id (a B<unsigned long> -value) or 0 if not set. - -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)|bn(3)> - -=head1 HISTORY - -BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id, -BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags -and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8 - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/openssl/trunk/doc/crypto/BN_CTX_new.pod b/openssl/trunk/doc/crypto/BN_CTX_new.pod deleted file mode 100644 index ad8d07db..00000000 --- a/openssl/trunk/doc/crypto/BN_CTX_new.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_CTX *BN_CTX_new(void); - - void BN_CTX_init(BN_CTX *c); - - 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_init() initializes an existing uninitialized -B<BN_CTX>. - -BN_CTX_free() frees the components of the B<BN_CTX>, and if it was -created by BN_CTX_new(), also the structure itself. -If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>, -L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX> -may be freed by BN_CTX_free(). - - -=head1 RETURN VALUES - -BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails, -it returns B<NULL> and sets an error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -BN_CTX_init() and BN_CTX_free() have no return values. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_start(3)|BN_CTX_start(3)> - -=head1 HISTORY - -BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay -and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_CTX_start.pod b/openssl/trunk/doc/crypto/BN_CTX_start.pod deleted file mode 100644 index dfcefe1a..00000000 --- a/openssl/trunk/doc/crypto/BN_CTX_start.pod +++ /dev/null @@ -1,52 +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)|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)|ERR_get_error(3)>. - - -=head1 SEE ALSO - -L<BN_CTX_new(3)|BN_CTX_new(3)> - -=head1 HISTORY - -BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_add.pod b/openssl/trunk/doc/crypto/BN_add.pod deleted file mode 100644 index 88c7a799..00000000 --- a/openssl/trunk/doc/crypto/BN_add.pod +++ /dev/null @@ -1,126 +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>). - -BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>). -I<r> may be the same B<BIGNUM> as I<a> or I<b>. -For multiplication by powers of 2, use L<BN_lshift(3)|BN_lshift(3)>. - -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)|BN_mod_mul_montgomery(3)> and -L<BN_mod_mul_reciprocal(3)|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)|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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, -L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)> - -=head1 HISTORY - -BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(), -BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and -OpenSSL. The I<ctx> argument to BN_mul() was added in SSLeay -0.9.1b. BN_exp() appeared in SSLeay 0.9.0. -BN_nnmod(), BN_mod_add(), BN_mod_sub(), and BN_mod_sqr() were added in -OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_add_word.pod b/openssl/trunk/doc/crypto/BN_add_word.pod deleted file mode 100644 index 70667d28..00000000 --- a/openssl/trunk/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)|ERR_get_error(3)>. - -BN_mod_word() and BN_div_word() return B<a>%B<w> on success and -B<(BN_ULONG)-1> if an error occurred. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> - -=head1 HISTORY - -BN_add_word() and BN_mod_word() are available in all versions of -SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and -BN_sub_word() and BN_mul_word() in SSLeay 0.9.0. - -Before 0.9.8a the return value for BN_div_word() and BN_mod_word() -in case of an error was 0. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_bn2bin.pod b/openssl/trunk/doc/crypto/BN_bn2bin.pod deleted file mode 100644 index a4b17ca6..00000000 --- a/openssl/trunk/doc/crypto/BN_bn2bin.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - -BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, -BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - int BN_bn2bin(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); - - char *BN_bn2hex(const BIGNUM *a); - char *BN_bn2dec(const BIGNUM *a); - int BN_hex2bn(BIGNUM **a, const char *str); - int BN_dec2bn(BIGNUM **a, const char *str); - - int BN_print(BIO *fp, const BIGNUM *a); - int BN_print_fp(FILE *fp, const BIGNUM *a); - - int BN_bn2mpi(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); - -=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_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_bn2hex() and BN_bn2dec() return printable strings containing the -hexadecimal and decimal encoding of B<a> respectively. For negative -numbers, the string is prefaced with a leading '-'. The string must be -freed later using OPENSSL_free(). - -BN_hex2bn() converts the string B<str> containing a hexadecimal number -to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new -B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's -length in hexadecimal digits. If the string starts with '-', the -number is negative. BN_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_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL -on error. BN_hex2bn() and BN_dec2bn() return the number's length in -hexadecimal or decimal digits, and 0 on error. - -BN_print_fp() and BN_print() return 1 on success, 0 on write errors. - -BN_bn2mpi() returns the length of the representation. BN_mpi2bn() -returns the B<BIGNUM>, and NULL on error. - -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_zero(3)|BN_zero(3)>, -L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>, -L<BN_num_bytes(3)|BN_num_bytes(3)> - -=head1 HISTORY - -BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available -in all versions of SSLeay and OpenSSL. - -BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and -BN_mpi2bn() were added in SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_cmp.pod b/openssl/trunk/doc/crypto/BN_cmp.pod deleted file mode 100644 index 23e9ed0b..00000000 --- a/openssl/trunk/doc/crypto/BN_cmp.pod +++ /dev/null @@ -1,48 +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)|bn(3)> - -=head1 HISTORY - -BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are -available in all versions of SSLeay and OpenSSL. -BN_is_odd() was added in SSLeay 0.8. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_copy.pod b/openssl/trunk/doc/crypto/BN_copy.pod deleted file mode 100644 index 388dd7df..00000000 --- a/openssl/trunk/doc/crypto/BN_copy.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -BN_copy, BN_dup - copy BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from); - - BIGNUM *BN_dup(const BIGNUM *from); - -=head1 DESCRIPTION - -BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM> -containing the value B<from>. - -=head1 RETURN VALUES - -BN_copy() returns B<to> on success, NULL on error. BN_dup() returns -the new B<BIGNUM>, and NULL on error. The error codes can be obtained -by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_generate_prime.pod b/openssl/trunk/doc/crypto/BN_generate_prime.pod deleted file mode 100644 index 7dccacbc..00000000 --- a/openssl/trunk/doc/crypto/BN_generate_prime.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - 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); - -=head1 DESCRIPTION - -BN_generate_prime() generates a pseudo-random prime number of B<num> -bits. -If B<ret> is not B<NULL>, it will be used to store the number. - -If B<callback> is not B<NULL>, it is called as follows: - -=over 4 - -=item * - -B<callback(0, i, cb_arg)> is called after generating the i-th -potential prime number. - -=item * - -While the number is being tested for primality, B<callback(1, j, -cb_arg)> is called as described below. - -=item * - -When a prime has been found, B<callback(2, i, cb_arg)> 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(). -The prime number generation has a negligible error probability. - -BN_is_prime() and BN_is_prime_fasttest() test if the number B<a> is -prime. The following tests are performed until one of them shows that -B<a> is composite; if B<a> passes all these tests, it is considered -prime. - -BN_is_prime_fasttest(), 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<callback> is not B<NULL>, -B<callback(1, -1, cb_arg)> is called. -If B<do_trial_division == 0>, this test is skipped. - -Both BN_is_prime() and BN_is_prime_fasttest() perform a Miller-Rabin -probabilistic primality test with B<checks> iterations. If -B<checks == 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<callback> is not B<NULL>, B<callback(1, j, cb_arg)> 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>. - -=head1 RETURN VALUES - -BN_generate_prime() returns the prime number on success, B<NULL> otherwise. - -BN_is_prime() returns 0 if the number is composite, 1 if it is -prime with an error probability of less than 0.25^B<checks>, and --1 on error. - -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)> - -=head1 HISTORY - -The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime() -were added in SSLeay 0.9.0. The B<ret> argument to BN_generate_prime() -was added in SSLeay 0.9.1. -BN_is_prime_fasttest() was added in OpenSSL 0.9.5. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_mod_inverse.pod b/openssl/trunk/doc/crypto/BN_mod_inverse.pod deleted file mode 100644 index 3ea3975c..00000000 --- a/openssl/trunk/doc/crypto/BN_mod_inverse.pod +++ /dev/null @@ -1,36 +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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> - -=head1 HISTORY - -BN_mod_inverse() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_mod_mul_montgomery.pod b/openssl/trunk/doc/crypto/BN_mod_mul_montgomery.pod deleted file mode 100644 index 6b16351b..00000000 --- a/openssl/trunk/doc/crypto/BN_mod_mul_montgomery.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init, -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_init(BN_MONT_CTX *ctx); - void BN_MONT_CTX_free(BN_MONT_CTX *mont); - - int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); - BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); - - int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_MONT_CTX *mont, BN_CTX *ctx); - - int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - - int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - -=head1 DESCRIPTION - -These functions implement Montgomery multiplication. They are used -automatically when L<BN_mod_exp(3)|BN_mod_exp(3)> is called with suitable input, -but they may be useful when several operations are to be performed -using the same modulus. - -BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure. -BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>. - -BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m> -by precomputing its inverse and a value R. - -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. - -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. - -The B<BN_MONT_CTX> structure is defined as follows: - - typedef struct bn_mont_ctx_st - { - int ri; /* number of bits in R */ - BIGNUM RR; /* R^2 (used to convert to Montgomery form) */ - BIGNUM N; /* The modulus */ - BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1 - * (Ni is only stored for bignum algorithm) */ - BN_ULONG n0; /* least significant word of Ni */ - int flags; - } BN_MONT_CTX; - -BN_to_montgomery() is a macro. - -=head1 RETURN VALUES - -BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL -on error. - -BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values. - -For the other functions, 1 is returned for success, 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=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)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_new(3)|BN_CTX_new(3)> - -=head1 HISTORY - -BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(), -BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery() -are available in all versions of SSLeay and OpenSSL. - -BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_mod_mul_reciprocal.pod b/openssl/trunk/doc/crypto/BN_mod_mul_reciprocal.pod deleted file mode 100644 index 74a216dd..00000000 --- a/openssl/trunk/doc/crypto/BN_mod_mul_reciprocal.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init, -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_init(BN_RECP_CTX *recp); - void BN_RECP_CTX_free(BN_RECP_CTX *recp); - - int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); - - int BN_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)|BN_mod_mul(3)> operation when the operation will be performed -repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m> -using B<recp>=1/B<m>, which is set as described below. B<ctx> is a -previously allocated B<BN_CTX> used for temporary variables. - -BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure. -BN_RECP_CTX_init() initializes an existing uninitialized B<BN_RECP>. - -BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it -was created by BN_RECP_CTX_new(), also the structure itself. - -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 is defined as follows: - - typedef struct bn_recp_ctx_st - { - BIGNUM N; /* the divisor */ - BIGNUM Nr; /* the reciprocal */ - int num_bits; - int shift; - int flags; - } BN_RECP_CTX; - -It cannot be shared between threads. - -=head1 RETURN VALUES - -BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL -on error. - -BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values. - -For the other functions, 1 is returned for success, 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_new(3)|BN_CTX_new(3)> - -=head1 HISTORY - -B<BN_RECP_CTX> was added in SSLeay 0.9.0. Before that, the function -BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal() -arguments were different. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_new.pod b/openssl/trunk/doc/crypto/BN_new.pod deleted file mode 100644 index ab7a105e..00000000 --- a/openssl/trunk/doc/crypto/BN_new.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_new(void); - - void BN_init(BIGNUM *); - - 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_init() -initializes an existing uninitialized B<BIGNUM>. - -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. - -=head1 RETURN VALUES - -BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails, -it returns B<NULL> and sets an error code that can be obtained -by L<ERR_get_error(3)|ERR_get_error(3)>. - -BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return -values. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in -all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay -0.9.1b. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_num_bytes.pod b/openssl/trunk/doc/crypto/BN_num_bytes.pod deleted file mode 100644 index a6a2e3f8..00000000 --- a/openssl/trunk/doc/crypto/BN_num_bytes.pod +++ /dev/null @@ -1,57 +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)|bn(3)>, L<DH_size(3)|DH_size(3)>, L<DSA_size(3)|DSA_size(3)>, -L<RSA_size(3)|RSA_size(3)> - -=head1 HISTORY - -BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in -all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_rand.pod b/openssl/trunk/doc/crypto/BN_rand.pod deleted file mode 100644 index 81f93c2e..00000000 --- a/openssl/trunk/doc/crypto/BN_rand.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -BN_rand, BN_pseudo_rand - 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> bits in length and stores it in B<rnd>. If B<top> is -1, the -most significant bit of the random number can be zero. If B<top> is 0, -it is set to 1, and if B<top> is 1, the two most significant bits of -the number will be set to 1, so that the product of two such random -numbers will always have 2*B<bits> length. If B<bottom> is true, the -number will be odd. - -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 <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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)> - -=head1 HISTORY - -BN_rand() is available in all versions of SSLeay and OpenSSL. -BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case -and the function BN_rand_range() were added in OpenSSL 0.9.6a. -BN_pseudo_rand_range() was added in OpenSSL 0.9.6c. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_set_bit.pod b/openssl/trunk/doc/crypto/BN_set_bit.pod deleted file mode 100644 index b7c47b9b..00000000 --- a/openssl/trunk/doc/crypto/BN_set_bit.pod +++ /dev/null @@ -1,66 +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>). 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>). 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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, L<BN_add(3)|BN_add(3)> - -=head1 HISTORY - -BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(), -BN_lshift(), BN_lshift1(), BN_rshift(), and BN_rshift1() are available -in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_swap.pod b/openssl/trunk/doc/crypto/BN_swap.pod deleted file mode 100644 index 79efaa14..00000000 --- a/openssl/trunk/doc/crypto/BN_swap.pod +++ /dev/null @@ -1,23 +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)|bn(3)> - -=head1 HISTORY - -BN_swap was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/BN_zero.pod b/openssl/trunk/doc/crypto/BN_zero.pod deleted file mode 100644 index b555ec39..00000000 --- a/openssl/trunk/doc/crypto/BN_zero.pod +++ /dev/null @@ -1,59 +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> - - int BN_zero(BIGNUM *a); - int BN_one(BIGNUM *a); - - const BIGNUM *BN_value_one(void); - - int BN_set_word(BIGNUM *a, unsigned long w); - unsigned long BN_get_word(BIGNUM *a); - -=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_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise. -BN_value_one() returns the constant. - -=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)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> - -=head1 HISTORY - -BN_zero(), BN_one() and BN_set_word() are available in all versions of -SSLeay and OpenSSL. BN_value_one() and BN_get_word() were added in -SSLeay 0.8. - -BN_value_one() was changed to return a true const BIGNUM * in OpenSSL -0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/CONF_modules_free.pod b/openssl/trunk/doc/crypto/CONF_modules_free.pod deleted file mode 100644 index af8ae6a5..00000000 --- a/openssl/trunk/doc/crypto/CONF_modules_free.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - - CONF_modules_free, CONF_modules_load, CONF_modules_unload - - OpenSSL configuration cleanup functions - -=head1 SYNOPSIS - - #include <openssl/conf.h> - - void CONF_modules_free(void); - void CONF_modules_unload(int all); - void CONF_modules_finish(void); - -=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 applications will only call CONF_modules_free() at application to -tidy up any configuration performed. - -=head1 RETURN VALUE - -None of the functions return a value. - -=head1 SEE ALSO - -L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_modules_load_file(3), CONF_modules_load_file(3)> - -=head1 HISTORY - -CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish() -first appeared in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/CONF_modules_load_file.pod b/openssl/trunk/doc/crypto/CONF_modules_load_file.pod deleted file mode 100644 index 9965d69b..00000000 --- a/openssl/trunk/doc/crypto/CONF_modules_load_file.pod +++ /dev/null @@ -1,60 +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 cutomized using B<flags>. - -CONF_modules_load() is idential to CONF_modules_load_file() except it -read 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 loads. - -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. - -=head1 RETURN VALUE - -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)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_free(3), CONF_free(3)>, L<err(3),err(3)> - -=head1 HISTORY - -CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/CRYPTO_set_ex_data.pod b/openssl/trunk/doc/crypto/CRYPTO_set_ex_data.pod deleted file mode 100644 index 1bd5bed6..00000000 --- a/openssl/trunk/doc/crypto/CRYPTO_set_ex_data.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); - - void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -These functions should only be used by applications to manipulate -B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and -B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example. - -B<CRYPTO_set_ex_data()> is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B<CRYPTO_set_ex_data()> call. - -=head1 RETURN VALUES - -B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure. - -B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, -L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)> - -=head1 HISTORY - -CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/DH_generate_key.pod b/openssl/trunk/doc/crypto/DH_generate_key.pod deleted file mode 100644 index 81f09fdf..00000000 --- a/openssl/trunk/doc/crypto/DH_generate_key.pod +++ /dev/null @@ -1,50 +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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)> - -=head1 HISTORY - -DH_generate_key() and DH_compute_key() are available in all versions -of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/DH_generate_parameters.pod b/openssl/trunk/doc/crypto/DH_generate_parameters.pod deleted file mode 100644 index 9081e9ea..00000000 --- a/openssl/trunk/doc/crypto/DH_generate_parameters.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - DH *DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - - int DH_check(DH *dh, int *codes); - -=head1 DESCRIPTION - -DH_generate_parameters() generates Diffie-Hellman parameters that can -be shared among a group of users, and returns them in a newly -allocated 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<callback> is not B<NULL>, it will be -called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime -number is generated, and when a prime has been found, B<callback(3, -0, cb_arg)> is called. - -DH_check() validates Diffie-Hellman parameters. It checks that B<p> is -a safe prime, and that B<g> is a suitable generator. In the case of an -error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or -DH_NOT_SUITABLE_GENERATOR are set in B<*codes>. -DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be -checked, i.e. it does not equal 2 or 5. - -=head1 RETURN VALUES - -DH_generate_parameters() returns a pointer to the DH structure, or -NULL if the parameter generation fails. The error codes can be -obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -DH_check() returns 1 if the check could be performed, 0 otherwise. - -=head1 NOTES - -DH_generate_parameters() may run for several hours before finding a -suitable prime. - -The parameters generated by DH_generate_parameters() are not to be -used in signature schemes. - -=head1 BUGS - -If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not -a usable generator. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DH_free(3)|DH_free(3)> - -=head1 HISTORY - -DH_check() is available in all versions of SSLeay and OpenSSL. -The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0. - -In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used -instead of DH_CHECK_P_NOT_SAFE_PRIME. - -=cut diff --git a/openssl/trunk/doc/crypto/DH_get_ex_new_index.pod b/openssl/trunk/doc/crypto/DH_get_ex_new_index.pod deleted file mode 100644 index fa5eab26..00000000 --- a/openssl/trunk/doc/crypto/DH_get_ex_new_index.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - int DH_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DH_set_ex_data(DH *d, int idx, void *arg); - - char *DH_get_ex_data(DH *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DH -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dh(3)|dh(3)> - -=head1 HISTORY - -DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/openssl/trunk/doc/crypto/DH_new.pod b/openssl/trunk/doc/crypto/DH_new.pod deleted file mode 100644 index 60c93009..00000000 --- a/openssl/trunk/doc/crypto/DH_new.pod +++ /dev/null @@ -1,40 +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. - -=head1 RETURN VALUES - -If the allocation fails, DH_new() returns B<NULL> and sets an error -code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns -a pointer to the newly allocated structure. - -DH_free() returns no value. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DH_generate_parameters(3)|DH_generate_parameters(3)>, -L<DH_generate_key(3)|DH_generate_key(3)> - -=head1 HISTORY - -DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/DH_set_method.pod b/openssl/trunk/doc/crypto/DH_set_method.pod deleted file mode 100644 index 73261fc4..00000000 --- a/openssl/trunk/doc/crypto/DH_set_method.pod +++ /dev/null @@ -1,129 +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> - #include <openssl/engine.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 dependant 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. - -=head1 THE DH_METHOD STRUCTURE - - typedef struct dh_meth_st - { - /* name of the implementation */ - const char *name; - - /* generate private and public DH values for key agreement */ - int (*generate_key)(DH *dh); - - /* compute shared secret */ - int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, - BN_MONT_CTX *m_ctx); - - /* called at DH_new */ - int (*init)(DH *dh); - - /* called at DH_free */ - int (*finish)(DH *dh); - - int flags; - - char *app_data; /* ?? */ - - } DH_METHOD; - -=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)|ERR_get_error(3)> if the allocation fails. Otherwise it -returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, DH_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a -default ENGINE is specified for DH functionality using an ENGINE API function, -that will override any DH defaults set using the DH API (ie. -DH_set_default_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in DH and other cryptographic -algorithms. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> - -=head1 HISTORY - -DH_set_default_method(), DH_get_default_method(), DH_set_method(), -DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. - -DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced -DH_set_default_method() and DH_get_default_method() respectively, and -DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than -B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DH API without -requiring changing these function prototypes. - -=cut diff --git a/openssl/trunk/doc/crypto/DH_size.pod b/openssl/trunk/doc/crypto/DH_size.pod deleted file mode 100644 index 97f26fda..00000000 --- a/openssl/trunk/doc/crypto/DH_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -DH_size - get Diffie-Hellman prime size - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - int DH_size(DH *dh); - -=head1 DESCRIPTION - -This function returns the Diffie-Hellman size in bytes. It can be used -to determine how much memory must be allocated for the shared secret -computed by DH_compute_key(). - -B<dh-E<gt>p> must not be B<NULL>. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)> - -=head1 HISTORY - -DH_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_SIG_new.pod b/openssl/trunk/doc/crypto/DSA_SIG_new.pod deleted file mode 100644 index 3ac61400..00000000 --- a/openssl/trunk/doc/crypto/DSA_SIG_new.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -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); - -=head1 DESCRIPTION - -DSA_SIG_new() allocates and initializes a 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. - -=head1 RETURN VALUES - -If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an -error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer -to the newly allocated structure. - -DSA_SIG_free() returns no value. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DSA_do_sign(3)|DSA_do_sign(3)> - -=head1 HISTORY - -DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_do_sign.pod b/openssl/trunk/doc/crypto/DSA_do_sign.pod deleted file mode 100644 index 5dfc733b..00000000 --- a/openssl/trunk/doc/crypto/DSA_do_sign.pod +++ /dev/null @@ -1,47 +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)|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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_SIG_new(3)|DSA_SIG_new(3)>, -L<DSA_sign(3)|DSA_sign(3)> - -=head1 HISTORY - -DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_dup_DH.pod b/openssl/trunk/doc/crypto/DSA_dup_DH.pod deleted file mode 100644 index 7f6f0d11..00000000 --- a/openssl/trunk/doc/crypto/DSA_dup_DH.pod +++ /dev/null @@ -1,36 +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)|ERR_get_error(3)>. - -=head1 NOTE - -Be careful to avoid small subgroup attacks when using this. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -DSA_dup_DH() was added in OpenSSL 0.9.4. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_generate_key.pod b/openssl/trunk/doc/crypto/DSA_generate_key.pod deleted file mode 100644 index af83ccfa..00000000 --- a/openssl/trunk/doc/crypto/DSA_generate_key.pod +++ /dev/null @@ -1,34 +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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)> - -=head1 HISTORY - -DSA_generate_key() is available since SSLeay 0.8. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_generate_parameters.pod b/openssl/trunk/doc/crypto/DSA_generate_parameters.pod deleted file mode 100644 index be7c924f..00000000 --- a/openssl/trunk/doc/crypto/DSA_generate_parameters.pod +++ /dev/null @@ -1,105 +0,0 @@ -=pod - -=head1 NAME - -DSA_generate_parameters - generate DSA parameters - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - 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); - -=head1 DESCRIPTION - -DSA_generate_parameters() generates primes p and q and a generator g -for use in the DSA. - -B<bits> is the length of the prime to be generated; the DSS allows a -maximum of 1024 bits. - -If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be -generated at random. Otherwise, the seed is used to generate -them. If the given seed does not yield a prime q, a new random -seed is chosen and placed at B<seed>. - -DSA_generate_parameters() 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<callback> is not B<NULL>, it will be -called as follows: - -=over 4 - -=item * - -When a candidate for q is generated, B<callback(0, m++, cb_arg)> is called -(m is 0 for the first candidate). - -=item * - -When a candidate for q has passed a test by trial division, -B<callback(1, -1, cb_arg)> is called. -While a candidate for q is tested by Miller-Rabin primality tests, -B<callback(1, i, cb_arg)> 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<callback(2, 0, cb_arg)> and -B<callback(3, 0, cb_arg)> are called. - -=item * - -Before a candidate for p (other than the first) is generated and tested, -B<callback(0, counter, cb_arg)> is called. - -=item * - -When a candidate for p has passed the test by trial division, -B<callback(1, -1, cb_arg)> is called. -While it is tested by the Miller-Rabin primality test, -B<callback(1, i, cb_arg)> 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<callback(2, 1, cb_arg)> is called. - -=item * - -When the generator has been found, B<callback(3, 1, cb_arg)> is called. - -=back - -=head1 RETURN VALUE - -DSA_generate_parameters() returns a pointer to the DSA structure, or -B<NULL> if the parameter generation fails. The error codes can be -obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 BUGS - -Seed lengths E<gt> 20 are not supported. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_free(3)|DSA_free(3)> - -=head1 HISTORY - -DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg> -argument was added in SSLeay 0.9.0. -In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called -in the inner loop of the Miller-Rabin test whenever it reached the -squaring step (the parameters to B<callback> did not reveal how many -witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)> -is called as in BN_is_prime(3), i.e. once for each witness. -=cut diff --git a/openssl/trunk/doc/crypto/DSA_get_ex_new_index.pod b/openssl/trunk/doc/crypto/DSA_get_ex_new_index.pod deleted file mode 100644 index 4612e708..00000000 --- a/openssl/trunk/doc/crypto/DSA_get_ex_new_index.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures - -=head1 SYNOPSIS - - #include <openssl/DSA.h> - - int DSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DSA_set_ex_data(DSA *d, int idx, void *arg); - - char *DSA_get_ex_data(DSA *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DSA -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)> - -=head1 HISTORY - -DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_new.pod b/openssl/trunk/doc/crypto/DSA_new.pod deleted file mode 100644 index 48e9b82a..00000000 --- a/openssl/trunk/doc/crypto/DSA_new.pod +++ /dev/null @@ -1,42 +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. - -=head1 RETURN VALUES - -If the allocation fails, DSA_new() returns B<NULL> and sets an error -code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer -to the newly allocated structure. - -DSA_free() returns no value. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, -L<DSA_generate_key(3)|DSA_generate_key(3)> - -=head1 HISTORY - -DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_set_method.pod b/openssl/trunk/doc/crypto/DSA_set_method.pod deleted file mode 100644 index bc3cfb1f..00000000 --- a/openssl/trunk/doc/crypto/DSA_set_method.pod +++ /dev/null @@ -1,143 +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> - #include <openssl/engine.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 dependant 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. - -DSA_new_method() allocates and initializes a DSA structure so that B<engine> -will be used for the DSA operations. If B<engine> is NULL, the default engine -for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD -controlled by DSA_set_default_method() is used. - -=head1 THE DSA_METHOD STRUCTURE - -struct - { - /* name of the implementation */ - const char *name; - - /* sign */ - DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, - DSA *dsa); - - /* pre-compute k^-1 and r */ - int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, - BIGNUM **rp); - - /* verify */ - int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - - /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some - implementations) */ - int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, - BIGNUM *a2, BIGNUM *p2, BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *in_mont); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, - const BIGNUM *p, const BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *m_ctx); - - /* called at DSA_new */ - int (*init)(DSA *DSA); - - /* called at DSA_free */ - int (*finish)(DSA *DSA); - - int flags; - - char *app_data; /* ?? */ - - } DSA_METHOD; - -=head1 RETURN VALUES - -DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective -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)|ERR_get_error(3)> if the allocation -fails. Otherwise it returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, DSA_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a -default ENGINE is specified for DSA functionality using an ENGINE API function, -that will override any DSA defaults set using the DSA API (ie. -DSA_set_default_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in DSA and other cryptographic -algorithms. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)> - -=head1 HISTORY - -DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), -DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. - -DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced -DSA_set_default_method() and DSA_get_default_method() respectively, and -DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than -B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DSA API without -requiring changing these function prototypes. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_sign.pod b/openssl/trunk/doc/crypto/DSA_sign.pod deleted file mode 100644 index 97389e8e..00000000 --- a/openssl/trunk/doc/crypto/DSA_sign.pod +++ /dev/null @@ -1,66 +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)|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)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_do_sign(3)|DSA_do_sign(3)> - -=head1 HISTORY - -DSA_sign() and DSA_verify() are available in all versions of SSLeay. -DSA_sign_setup() was added in SSLeay 0.8. - -=cut diff --git a/openssl/trunk/doc/crypto/DSA_size.pod b/openssl/trunk/doc/crypto/DSA_size.pod deleted file mode 100644 index ba4f6503..00000000 --- a/openssl/trunk/doc/crypto/DSA_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -DSA_size - get DSA signature size - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - int DSA_size(const DSA *dsa); - -=head1 DESCRIPTION - -This function returns the size of an ASN.1 encoded DSA signature in -bytes. It can be used to determine how much memory must be allocated -for a DSA signature. - -B<dsa-E<gt>q> must not be B<NULL>. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)> - -=head1 HISTORY - -DSA_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_GET_LIB.pod b/openssl/trunk/doc/crypto/ERR_GET_LIB.pod deleted file mode 100644 index 2a129da0..00000000 --- a/openssl/trunk/doc/crypto/ERR_GET_LIB.pod +++ /dev/null @@ -1,51 +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)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in -all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_clear_error.pod b/openssl/trunk/doc/crypto/ERR_clear_error.pod deleted file mode 100644 index 566e1f4e..00000000 --- a/openssl/trunk/doc/crypto/ERR_clear_error.pod +++ /dev/null @@ -1,29 +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)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -ERR_clear_error() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_error_string.pod b/openssl/trunk/doc/crypto/ERR_error_string.pod deleted file mode 100644 index cdfa7fe1..00000000 --- a/openssl/trunk/doc/crypto/ERR_error_string.pod +++ /dev/null @@ -1,73 +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 120 -bytes long. If I<buf> is B<NULL>, the error string is placed in a -static buffer. -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. - -The OpenSSL error strings should be loaded by calling -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL -applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> -first. -If there is no text string registered for the given error code, -the error string will contain the numeric code. - -L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print -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)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> -L<ERR_print_errors(3)|ERR_print_errors(3)> - -=head1 HISTORY - -ERR_error_string() is available in all versions of SSLeay and OpenSSL. -ERR_error_string_n() was added in OpenSSL 0.9.6. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_get_error.pod b/openssl/trunk/doc/crypto/ERR_get_error.pod deleted file mode 100644 index 34443045..00000000 --- a/openssl/trunk/doc/crypto/ERR_get_error.pod +++ /dev/null @@ -1,76 +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)|ERR_GET_LIB(3)> for obtaining information about -location and reason of the error, and -L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error -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_get_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>. If it has been allocated by OPENSSL_malloc(), -*B<flags>&B<ERR_TXT_MALLOCED> is true. - -=head1 RETURN VALUES - -The error code, or 0 if there is no error in the queue. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> - -=head1 HISTORY - -ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and -ERR_peek_error_line() are available in all versions of SSLeay and -OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() -were added in SSLeay 0.9.0. -ERR_peek_last_error(), ERR_peek_last_error_line() and -ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_load_crypto_strings.pod b/openssl/trunk/doc/crypto/ERR_load_crypto_strings.pod deleted file mode 100644 index 9bdec75a..00000000 --- a/openssl/trunk/doc/crypto/ERR_load_crypto_strings.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - -load and free error strings - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_load_crypto_strings(void); - void ERR_free_strings(void); - - #include <openssl/ssl.h> - - void SSL_load_error_strings(void); - -=head1 DESCRIPTION - -ERR_load_crypto_strings() registers the error strings for all -B<libcrypto> functions. SSL_load_error_strings() does the same, -but also registers the B<libssl> error strings. - -One of these functions should be called before generating -textual error messages. However, this is not required when memory -usage is an issue. - -ERR_free_strings() frees all previously loaded error strings. - -=head1 RETURN VALUES - -ERR_load_crypto_strings(), SSL_load_error_strings() and -ERR_free_strings() return no values. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)> - -=head1 HISTORY - -ERR_load_error_strings(), SSL_load_error_strings() and -ERR_free_strings() are available in all versions of SSLeay and -OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_load_strings.pod b/openssl/trunk/doc/crypto/ERR_load_strings.pod deleted file mode 100644 index 5acdd0ed..00000000 --- a/openssl/trunk/doc/crypto/ERR_load_strings.pod +++ /dev/null @@ -1,54 +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 a new library number. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> - -=head1 HISTORY - -ERR_load_error_strings() and ERR_PACK() are available in all versions -of SSLeay and OpenSSL. ERR_get_next_error_library() was added in -SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_print_errors.pod b/openssl/trunk/doc/crypto/ERR_print_errors.pod deleted file mode 100644 index b100a5fa..00000000 --- a/openssl/trunk/doc/crypto/ERR_print_errors.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -ERR_print_errors, ERR_print_errors_fp - print error messages - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_print_errors(BIO *bp); - void ERR_print_errors_fp(FILE *fp); - -=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>. - - -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)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> - -=head1 HISTORY - -ERR_print_errors() and ERR_print_errors_fp() -are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_put_error.pod b/openssl/trunk/doc/crypto/ERR_put_error.pod deleted file mode 100644 index acd241fb..00000000 --- a/openssl/trunk/doc/crypto/ERR_put_error.pod +++ /dev/null @@ -1,44 +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, ...); - -=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. - -L<ERR_load_strings(3)|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. - -=head1 RETURN VALUES - -ERR_put_error() and ERR_add_error_data() return -no values. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> - -=head1 HISTORY - -ERR_put_error() is available in all versions of SSLeay and OpenSSL. -ERR_add_error_data() was added in SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_remove_state.pod b/openssl/trunk/doc/crypto/ERR_remove_state.pod deleted file mode 100644 index 72925fb9..00000000 --- a/openssl/trunk/doc/crypto/ERR_remove_state.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -ERR_remove_state - free a thread's error queue - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_remove_state(unsigned long pid); - -=head1 DESCRIPTION - -ERR_remove_state() frees the error queue associated with thread B<pid>. -If B<pid> == 0, the current thread will have its error queue removed. - -Since error queue data structures are allocated automatically for new -threads, they must be freed when threads are terminated in order to -avoid memory leaks. - -=head1 RETURN VALUE - -ERR_remove_state() returns no value. - -=head1 SEE ALSO - -L<err(3)|err(3)> - -=head1 HISTORY - -ERR_remove_state() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ERR_set_mark.pod b/openssl/trunk/doc/crypto/ERR_set_mark.pod deleted file mode 100644 index d3ca4f2e..00000000 --- a/openssl/trunk/doc/crypto/ERR_set_mark.pod +++ /dev/null @@ -1,38 +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)|err(3)> - -=head1 HISTORY - -ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8. - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_BytesToKey.pod b/openssl/trunk/doc/crypto/EVP_BytesToKey.pod deleted file mode 100644 index d375c46e..00000000 --- a/openssl/trunk/doc/crypto/EVP_BytesToKey.pod +++ /dev/null @@ -1,67 +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> paramter 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 peform 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 more standard algorithms such as PKCS#5 -v2.0 for key derivation. - -=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 concatentaion, 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 - -EVP_BytesToKey() returns the size of the derived key in bytes. - -=head1 SEE ALSO - -L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_DigestInit.pod b/openssl/trunk/doc/crypto/EVP_DigestInit.pod deleted file mode 100644 index 130cd7f6..00000000 --- a/openssl/trunk/doc/crypto/EVP_DigestInit.pod +++ /dev/null @@ -1,256 +0,0 @@ -=pod - -=head1 NAME - -EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, -EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, -EVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, -EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, -EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2, -EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - -EVP digest routines - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - void EVP_MD_CTX_init(EVP_MD_CTX *ctx); - EVP_MD_CTX *EVP_MD_CTX_create(void); - - int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); - int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); - int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, - unsigned int *s); - - int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); - void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); - - int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); - - int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); - int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, - unsigned int *s); - - int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); - - #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ - - - #define EVP_MD_type(e) ((e)->type) - #define EVP_MD_pkey_type(e) ((e)->pkey_type) - #define EVP_MD_size(e) ((e)->md_size) - #define EVP_MD_block_size(e) ((e)->block_size) - - #define EVP_MD_CTX_md(e) (e)->digest) - #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest) - #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) - #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) - - const EVP_MD *EVP_md_null(void); - const EVP_MD *EVP_md2(void); - const EVP_MD *EVP_md5(void); - const EVP_MD *EVP_sha(void); - const EVP_MD *EVP_sha1(void); - const EVP_MD *EVP_dss(void); - const EVP_MD *EVP_dss1(void); - const EVP_MD *EVP_mdc2(void); - const EVP_MD *EVP_ripemd160(void); - - const EVP_MD *EVP_get_digestbyname(const char *name); - #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) - #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) - -=head1 DESCRIPTION - -The EVP digest routines are a high level interface to message digests. - -EVP_MD_CTX_init() initializes digest contet B<ctx>. - -EVP_MD_CTX_create() allocates, initializes and returns a digest contet. - -EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest -B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this -function. B<type> will typically be supplied by a functionsuch as EVP_sha1(). -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_cleanup() cleans up digest context B<ctx>, it should be called -after a digest context is no longer needed. - -EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the -space allocated to it, it should be called only on a context created -using EVP_MD_CTX_create(). - -EVP_MD_CTX_copy_ex() can be used to copy the message digest state from -B<in> to B<out>. This is useful if large amounts of data are to be -hashed which only differ in the last few bytes. B<out> must be initialized -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 -contet 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>. This "link" between digests and signature -algorithms may not be retained in future versions of OpenSSL. - -EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160() -return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest -algorithms respectively. The associated signature algorithm is RSA in each case. - -EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest -algorithms but using DSS (DSA) for the signature algorithm. - -EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it -returns is of zero length. - -EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() -return an B<EVP_MD> structure when passed a digest name, a digest NID or -an ASN1_OBJECT structure respectively. The digest table must be initialized -using, for example, OpenSSL_add_all_digests() for these functions to work. - -=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(e), EVP_MD_size(), -EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block -size in bytes. - -EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), -EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the -corresponding EVP_MD structures. - -EVP_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. - -SHA1 is the digest of choice for new applications. 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. - -In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use -memory leaks will occur. - -=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; - - OpenSSL_add_all_digests(); - - 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); - } - - EVP_MD_CTX_init(&mdctx); - 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_cleanup(&mdctx); - - printf("Digest is: "); - for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); - printf("\n"); - } - -=head1 BUGS - -The link between digests and signing algorithms results in a situation where -EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS -even though they are identical digests. - -=head1 SEE ALSO - -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> - -=head1 HISTORY - -EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), -EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() -and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7. - -EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), -EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were -changed to return truely const EVP_MD * in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_EncryptInit.pod b/openssl/trunk/doc/crypto/EVP_EncryptInit.pod deleted file mode 100644 index 8271d3df..00000000 --- a/openssl/trunk/doc/crypto/EVP_EncryptInit.pod +++ /dev/null @@ -1,511 +0,0 @@ -=pod - -=head1 NAME - -EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate, -EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate, -EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate, -EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, -EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, -EVP_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 cipher routines - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); - - 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); - int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); - - const EVP_CIPHER *EVP_get_cipherbyname(const char *name); - #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) - #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) - - #define EVP_CIPHER_nid(e) ((e)->nid) - #define EVP_CIPHER_block_size(e) ((e)->block_size) - #define EVP_CIPHER_key_length(e) ((e)->key_len) - #define EVP_CIPHER_iv_length(e) ((e)->iv_len) - #define EVP_CIPHER_flags(e) ((e)->flags) - #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE) - int EVP_CIPHER_type(const EVP_CIPHER *ctx); - - #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) - #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) - #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) - #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len) - #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) - #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data) - #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d)) - #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) - #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags) - #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE) - - 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_init() initializes cipher contex B<ctx>. - -EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption -with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized -before calling this function. B<type> is normally supplied -by a function such as EVP_des_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<outl> should contain sufficient -room. The actual number of bytes written is placed in B<outl>. - -If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts -the "final" data, that is any data that remains in a partial block. -It uses L<standard block padding|/NOTES> (aka PKCS padding). The encrypted -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_cleanup() clears all information from a cipher context -and free up any allocated memory associate with it. It should be called -after all operations using a cipher are complete so sensitive information -does not remain in memory. - -EVP_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> paramter does not need to be -initialized and they always use the default cipher implementation. - -EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a -similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and -EVP_CipherFinal_ex() except B<ctx> is automatically cleaned up -after the call. - -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. 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_IV_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. Currently only the RC2 effective key length and the number of rounds of -RC5 can be set. - -=head1 RETURN VALUES - -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_cleanup() 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 1 for -success or zero for failure. - -=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_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) - -DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void) - -Two key triple DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void) - -Three key triple DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_desx_cbc(void) - -DESX algorithm in CBC mode. - -=item EVP_rc4(void) - -RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. - -=item EVP_rc4_40(void) - -RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4() -and the EVP_CIPHER_CTX_set_key_length() function. - -=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void) - -IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) - -RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key -length cipher with an additional parameter called "effective key bits" or "effective key length". -By default both are set to 128 bits. - -=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void) - -RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits. -These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and -EVP_CIPHER_CTX_ctrl() to set the key length and effective key length. - -=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); - -Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key -length cipher. - -=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void) - -CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key -length cipher. - -=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) - -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. - -=back - -=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. - -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. - -=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 - -Get the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); - -Get the RC2 effective key length: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); - -Set the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); - -Set the effective key length used in RC2: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); - -Encrypt a string using blowfish: - - int do_crypt(char *outfile) - { - unsigned char outbuf[1024]; - int outlen, tmplen; - /* Bogus key and IV: we'd normally set these from - * another source. - */ - unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; - unsigned char iv[] = {1,2,3,4,5,6,7,8}; - char intext[] = "Some Crypto Text"; - EVP_CIPHER_CTX ctx; - FILE *out; - EVP_CIPHER_CTX_init(&ctx); - EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv); - - if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext))) - { - /* Error */ - return 0; - } - /* Buffer passed to EVP_EncryptFinal() must be after data just - * encrypted to avoid overwriting it. - */ - if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) - { - /* Error */ - return 0; - } - outlen += tmplen; - EVP_CIPHER_CTX_cleanup(&ctx); - /* Need binary mode for fopen because encrypted data is - * binary data. Also cannot use strlen() on it because - * it wont be null terminated and may contain embedded - * nulls. - */ - out = fopen(outfile, "wb"); - fwrite(outbuf, 1, outlen, out); - fclose(out); - return 1; - } - -The ciphertext from the above example can be decrypted using the B<openssl> -utility with the command line: - - S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d> - -General encryption, decryption function example using FILE I/O and RC2 with an -80 bit key: - - int do_crypt(FILE *in, FILE *out, int do_encrypt) - { - /* Allow enough space in output buffer for additional block */ - inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; - int inlen, outlen; - /* Bogus key and IV: we'd normally set these from - * another source. - */ - unsigned char key[] = "0123456789"; - unsigned char iv[] = "12345678"; - /* Don't set key or IV because we will modify the parameters */ - EVP_CIPHER_CTX_init(&ctx); - EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt); - EVP_CIPHER_CTX_set_key_length(&ctx, 10); - /* We finished modifying parameters so now we can set key and IV */ - EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt); - - for(;;) - { - inlen = fread(inbuf, 1, 1024, in); - if(inlen <= 0) break; - if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen)) - { - /* Error */ - EVP_CIPHER_CTX_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - } - if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) - { - /* Error */ - EVP_CIPHER_CTX_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - - EVP_CIPHER_CTX_cleanup(&ctx); - return 1; - } - - -=head1 SEE ALSO - -L<evp(3)|evp(3)> - -=head1 HISTORY - -EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), -EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), -EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in -OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_OpenInit.pod b/openssl/trunk/doc/crypto/EVP_OpenInit.pod deleted file mode 100644 index 2e710da9..00000000 --- a/openssl/trunk/doc/crypto/EVP_OpenInit.pod +++ /dev/null @@ -1,63 +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)|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)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_SealInit(3)|EVP_SealInit(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_PKEY_new.pod b/openssl/trunk/doc/crypto/EVP_PKEY_new.pod deleted file mode 100644 index 10687e45..00000000 --- a/openssl/trunk/doc/crypto/EVP_PKEY_new.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_new, EVP_PKEY_free - private key allocation functions. - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - EVP_PKEY *EVP_PKEY_new(void); - 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. - -EVP_PKEY_free() frees up the private key B<key>. - -=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)|EVP_PKEY_set1_RSA(3)> should be used. - -=head1 RETURN VALUES - -EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> -structure of B<NULL> if an error occurred. - -EVP_PKEY_free() does not return a value. - -=head1 SEE ALSO - -L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_PKEY_set1_RSA.pod b/openssl/trunk/doc/crypto/EVP_PKEY_set1_RSA.pod deleted file mode 100644 index 2db692e2..00000000 --- a/openssl/trunk/doc/crypto/EVP_PKEY_set1_RSA.pod +++ /dev/null @@ -1,80 +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_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, -EVP_PKEY_type - 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); - - 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_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_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() -and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key> -however these use the supplied B<key> internally and so B<key> -will be freed when the parent B<pkey> is freed. - -EVP_PKEY_type() returns the type of key corresponding to the value -B<type>. The type of a key can be obtained with -EVP_PKEY_type(pkey->type). The return value will be EVP_PKEY_RSA, -EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding -key types or NID_undef if the key type is unassigned. - -=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() -EVP_PKEY_assign_EC_KEY() are implemented as macros. - -=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. - -=head1 SEE ALSO - -L<EVP_PKEY_new(3)|EVP_PKEY_new(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_SealInit.pod b/openssl/trunk/doc/crypto/EVP_SealInit.pod deleted file mode 100644 index 7d793e19..00000000 --- a/openssl/trunk/doc/crypto/EVP_SealInit.pod +++ /dev/null @@ -1,85 +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_des_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)|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)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_OpenInit(3)|EVP_OpenInit(3)> - -=head1 HISTORY - -EVP_SealFinal() did not return a value before OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_SignInit.pod b/openssl/trunk/doc/crypto/EVP_SignInit.pod deleted file mode 100644 index b6e62ce7..00000000 --- a/openssl/trunk/doc/crypto/EVP_SignInit.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - -EVP_SignInit, 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 initialized with -EVP_MD_CTX_init() 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>. 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)|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)|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(). - -=head1 SEE ALSO - -L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> - -=head1 HISTORY - -EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_SignInit_ex() was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/EVP_VerifyInit.pod b/openssl/trunk/doc/crypto/EVP_VerifyInit.pod deleted file mode 100644 index b6afaede..00000000 --- a/openssl/trunk/doc/crypto/EVP_VerifyInit.pod +++ /dev/null @@ -1,86 +0,0 @@ -=pod - -=head1 NAME - -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 initialized by calling -EVP_MD_CTX_init() 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)|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)|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(). - -=head1 SEE ALSO - -L<evp(3)|evp(3)>, -L<EVP_SignInit(3)|EVP_SignInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> - -=head1 HISTORY - -EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_VerifyInit_ex() was added in OpenSSL 0.9.7 - -=cut diff --git a/openssl/trunk/doc/crypto/OBJ_nid2obj.pod b/openssl/trunk/doc/crypto/OBJ_nid2obj.pod deleted file mode 100644 index 7dcc0792..00000000 --- a/openssl/trunk/doc/crypto/OBJ_nid2obj.pod +++ /dev/null @@ -1,149 +0,0 @@ -=pod - -=head1 NAME - -OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, -OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility -functions - -=head1 SYNOPSIS - - 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 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); - void OBJ_cleanup(void); - -=head1 DESCRIPTION - -The ASN1 object utility functions process ASN1_OBJECT structures which are -a representation of the ASN1 OBJECT IDENTIFIER (OID) type. - -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 respresentation 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. - -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_cleanup() cleans up OpenSSLs internal object table: this should -be called before an application exits if any new objects were added -using OBJ_create(). - -=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. - -=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)|ERR_get_error(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/OPENSSL_Applink.pod b/openssl/trunk/doc/crypto/OPENSSL_Applink.pod deleted file mode 100644 index e54de12c..00000000 --- a/openssl/trunk/doc/crypto/OPENSSL_Applink.pod +++ /dev/null @@ -1,21 +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 <openssl>/ms/applink.c. - -=cut diff --git a/openssl/trunk/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/openssl/trunk/doc/crypto/OPENSSL_VERSION_NUMBER.pod deleted file mode 100644 index c39ac35e..00000000 --- a/openssl/trunk/doc/crypto/OPENSSL_VERSION_NUMBER.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number - -=head1 SYNOPSIS - - #include <openssl/opensslv.h> - #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL - - #include <openssl/crypto.h> - long SSLeay(void); - const char *SSLeay_version(int t); - -=head1 DESCRIPTION - -OPENSSL_VERSION_NUMBER is a numeric release version identifier: - - MMNNFFPPS: 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. - - -For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. - -SSLeay() returns this number. The return value can be compared to the -macro to make sure that the correct version of the library has been -loaded, especially when using DLLs on Windows systems. - -SSLeay_version() returns different strings depending on B<t>: - -=over 4 - -=item SSLEAY_VERSION - -The text variant of the version number and the release date. For example, -"OpenSSL 0.9.5a 1 Apr 2000". - -=item SSLEAY_CFLAGS - -The compiler flags set for the compilation process in the form -"compiler: ..." if available or "compiler: information not available" -otherwise. - -=item SSLEAY_BUILT_ON - -The date of the build process in the form "built on: ..." if available -or "built on: date not available" otherwise. - -=item SSLEAY_PLATFORM - -The "Configure" target of the library build in the form "platform: ..." -if available or "platform: information not available" otherwise. - -=item SSLEAY_DIR - -The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" -if available or "OPENSSLDIR: N/A" otherwise. - -=back - -For an unknown B<t>, the text "not available" is returned. - -=head1 RETURN VALUE - -The version number. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)> - -=head1 HISTORY - -SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and OpenSSL. -OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL. -B<SSLEAY_DIR> was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/OPENSSL_config.pod b/openssl/trunk/doc/crypto/OPENSSL_config.pod deleted file mode 100644 index e7bba2aa..00000000 --- a/openssl/trunk/doc/crypto/OPENSSL_config.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions - -=head1 SYNOPSIS - - #include <openssl/conf.h> - - void OPENSSL_config(const char *config_name); - void OPENSSL_no_config(void); - -=head1 DESCRIPTION - -OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> -configuration file name using B<config_name>. If B<config_name> is NULL then -the default name B<openssl_conf> will be used. Any errors are ignored. Further -calls to OPENSSL_config() will have no effect. The configuration file format -is documented in the L<conf(5)|conf(5)> manual page. - -OPENSSL_no_config() disables configuration. If called before OPENSSL_config() -no configuration takes place. - -=head1 NOTES - -It is B<strongly> recommended that B<all> new applications call OPENSSL_config() -or the more sophisticated functions such as CONF_modules_load() during -initialization (that is before starting any threads). By doing this -an application does not need to keep track of all configuration options -and some new functionality can be supported automatically. - -It is also possible to automatically call OPENSSL_config() when an application -calls OPENSSL_add_all_algorithms() by compiling an application with the -preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration -can be added without source changes. - -The environment variable B<OPENSSL_CONF> can be set to specify the location -of the configuration file. - -Currently ASN1 OBJECTs and ENGINE configuration can be performed future -versions of OpenSSL will add new configuration options. - -There are several reasons why calling the OpenSSL configuration routines is -advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7. -In OpenSSL 0.9.7 control functions can be supported by ENGINEs, this can be -used (among other things) to load dynamic ENGINEs from shared libraries (DSOs). -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. - -Applications should free up configuration at application closedown by calling -CONF_modules_free(). - -=head1 RESTRICTIONS - -The OPENSSL_config() function is designed to be a very simple "call it and -forget it" function. As a result its behaviour is somewhat limited. It ignores -all errors silently and it can only load from the standard configuration file -location for example. - -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_load_modules() directly. - -=head1 RETURN VALUES - -Neither OPENSSL_config() nor OPENSSL_no_config() return a value. - -=head1 SEE ALSO - -L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>, -L<CONF_modules_free(3),CONF_modules_free(3)> - -=head1 HISTORY - -OPENSSL_config() and OPENSSL_no_config() first appeared in OpenSSL 0.9.7 - -=cut diff --git a/openssl/trunk/doc/crypto/OPENSSL_ia32cap.pod b/openssl/trunk/doc/crypto/OPENSSL_ia32cap.pod deleted file mode 100644 index 121a8dde..00000000 --- a/openssl/trunk/doc/crypto/OPENSSL_ia32cap.pod +++ /dev/null @@ -1,35 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_ia32cap - finding the IA-32 processor capabilities - -=head1 SYNOPSIS - - unsigned long *OPENSSL_ia32cap_loc(void); - #define OPENSSL_ia32cap (*(OPENSSL_ia32cap_loc())) - -=head1 DESCRIPTION - -Value returned by OPENSSL_ia32cap_loc() is address of a variable -containing IA-32 processor capabilities bit vector as it appears in EDX -register after executing CPUID instruction with EAX=1 input value (see -Intel Application Note #241618). Naturally it's meaningful on IA-32[E] -platforms only. The variable is normally set up automatically upon -toolkit initialization, but can be manipulated afterwards to modify -crypto library behaviour. For the moment of this writing three bits are -significant, namely bit #28 denoting Hyperthreading, which is used to -distinguish Intel P4 core, bit #26 denoting SSE2 support, and bit #4 -denoting presence of Time-Stamp Counter. Clearing bit #26 at run-time -for example disables high-performance SSE2 code present in the crypto -library. You might have to do this if target OpenSSL application is -executed on SSE2 capable CPU, but under control of OS which does not -support SSE2 extentions. Even though you can manipulate the value -programmatically, you most likely will find it more appropriate to set -up an environment variable with the same name prior starting target -application, e.g. 'env OPENSSL_ia32cap=0x10 apps/openssl', to achieve -same effect without modifying the application source code. -Alternatively you can reconfigure the toolkit with no-sse2 option and -recompile. - -=cut diff --git a/openssl/trunk/doc/crypto/OPENSSL_load_builtin_modules.pod b/openssl/trunk/doc/crypto/OPENSSL_load_builtin_modules.pod deleted file mode 100644 index f14dfaf0..00000000 --- a/openssl/trunk/doc/crypto/OPENSSL_load_builtin_modules.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_load_builtin_modules - 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)|conf(3)>, L<OPENSSL_config(3)|OPENSSL_config(3)> - -=head1 HISTORY - -These functions first appeared in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/OpenSSL_add_all_algorithms.pod b/openssl/trunk/doc/crypto/OpenSSL_add_all_algorithms.pod deleted file mode 100644 index e63411b5..00000000 --- a/openssl/trunk/doc/crypto/OpenSSL_add_all_algorithms.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests - -add algorithms to internal table - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - void OpenSSL_add_all_algorithms(void); - void OpenSSL_add_all_ciphers(void); - void OpenSSL_add_all_digests(void); - - void EVP_cleanup(void); - -=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(). - -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. - -EVP_cleanup() removes all ciphers and digests from the table. - -=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)|evp(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/PKCS12_create.pod b/openssl/trunk/doc/crypto/PKCS12_create.pod deleted file mode 100644 index de7cab2b..00000000 --- a/openssl/trunk/doc/crypto/PKCS12_create.pod +++ /dev/null @@ -1,75 +0,0 @@ -=pod - -=head1 NAME - -PKCS12_create - create a PKCS#12 structure - -=head1 SYNOPSIS - - #include <openssl/pkcs12.h> - - PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, STACK_OF(X509) *ca, - int nid_key, int nid_cert, int iter, int mac_iter, int keytype); - -=head1 DESCRIPTION - -PKCS12_create() creates a PKCS#12 structure. - -B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for -the supplied certifictate and key. B<pkey> is the private key to include in -the 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. - -=head1 NEW FUNCTIONALITY IN OPENSSL 0.9.8 - -Some additional functionality was added to PKCS12_create() in OpenSSL -0.9.8. These extensions are detailed below. - -If a certificate contains an B<alias> or B<keyid> then this will be -used for the corresponding B<friendlyName> or B<localKeyID> in the -PKCS12 structure. - -Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or -certficate is required. In previous versions both had to be present or -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)|d2i_PKCS12(3)> - -=head1 HISTORY - -PKCS12_create was added in OpenSSL 0.9.3 - -=cut diff --git a/openssl/trunk/doc/crypto/PKCS12_parse.pod b/openssl/trunk/doc/crypto/PKCS12_parse.pod deleted file mode 100644 index 51344f88..00000000 --- a/openssl/trunk/doc/crypto/PKCS12_parse.pod +++ /dev/null @@ -1,50 +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 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 store in the private key B<EVP_PKEY> structure. - -=head1 SEE ALSO - -L<d2i_PKCS12(3)|d2i_PKCS12(3)> - -=head1 HISTORY - -PKCS12_parse was added in OpenSSL 0.9.3 - -=cut diff --git a/openssl/trunk/doc/crypto/PKCS7_decrypt.pod b/openssl/trunk/doc/crypto/PKCS7_decrypt.pod deleted file mode 100644 index b0ca067b..00000000 --- a/openssl/trunk/doc/crypto/PKCS7_decrypt.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure - -=head1 SYNOPSIS - -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 - -OpenSSL_add_all_algorithms() (or equivalent) should be called before using this -function or errors about unknown algorithms will occur. - -Although the recipients certificate is not needed to decrypt the data it is needed -to locate the appropriate (of possible several) recipients in the PKCS#7 structure. - -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)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> - -=head1 HISTORY - -PKCS7_decrypt() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/trunk/doc/crypto/PKCS7_encrypt.pod b/openssl/trunk/doc/crypto/PKCS7_encrypt.pod deleted file mode 100644 index 1a507b22..00000000 --- a/openssl/trunk/doc/crypto/PKCS7_encrypt.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_encrypt - create a PKCS#7 envelopedData structure - -=head1 SYNOPSIS - -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. - -=head1 RETURN VALUES - -PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred. -The error can be obtained from ERR_get_error(3). - -=head1 BUGS - -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)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -PKCS7_decrypt() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/trunk/doc/crypto/PKCS7_sign.pod b/openssl/trunk/doc/crypto/PKCS7_sign.pod deleted file mode 100644 index ffd0c734..00000000 --- a/openssl/trunk/doc/crypto/PKCS7_sign.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_sign - create a PKCS#7 signedData structure - -=head1 SYNOPSIS - -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 corresponsding 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_PARTSIGN> 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. Currently the -flag B<PKCS7_DETACHED> B<must> also be set. - -=head1 NOTES - -Currently the flag B<PKCS7_PARTSIGN> is only supported for detached -data. If this flag 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. - -At present only the SMIME_write_PKCS7() function properly finalizes the -structure. - -=head1 BUGS - -PKCS7_sign() is somewhat limited. It does not support multiple signers, some -advanced attributes such as counter signatures are not supported. - -The SHA1 digest algorithm is currently always used. - -When the signed data is not detached it will be stored in memory within the -B<PKCS7> structure. This effectively limits the size of messages which can be -signed due to memory restraints. There should be a way to sign data without -having to hold it all in memory, this would however require fairly major -revisions of the OpenSSL ASN1 code. - - -=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)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> - -=head1 HISTORY - -PKCS7_sign() was added to OpenSSL 0.9.5 - -The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8 - -=cut diff --git a/openssl/trunk/doc/crypto/PKCS7_verify.pod b/openssl/trunk/doc/crypto/PKCS7_verify.pod deleted file mode 100644 index 3490b5dc..00000000 --- a/openssl/trunk/doc/crypto/PKCS7_verify.pod +++ /dev/null @@ -1,116 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_verify - verify a PKCS#7 signedData structure - -=head1 SYNOPSIS - -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 certficate 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>. - -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 1 for a successful verification and zero or a negative -value if an error occurs. - -PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred. - -The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> - -=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)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)> - -=head1 HISTORY - -PKCS7_verify() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/trunk/doc/crypto/RAND_add.pod b/openssl/trunk/doc/crypto/RAND_add.pod deleted file mode 100644 index 67c66f3e..00000000 --- a/openssl/trunk/doc/crypto/RAND_add.pod +++ /dev/null @@ -1,77 +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); - - int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); - void RAND_screen(void); - -=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)|RAND_egd(3)> -or L<RAND_load_file(3)|RAND_load_file(3)>. - -RAND_seed() is equivalent to RAND_add() when B<num == entropy>. - -RAND_event() collects the entropy from Windows events such as mouse -movements and other user interaction. It should be called with the -B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to -the window procedure. It will estimate the entropy contained in the -event message (if any), and add it to the PRNG. The program can then -process the messages as usual. - -The RAND_screen() function is available for the convenience of Windows -programmers. It adds the current contents of the screen to the PRNG. -For applications that can catch Windows events, seeding the PRNG by -calling RAND_event() is a significantly better source of -randomness. It should be noted that both methods cannot be used on -servers that run without user interaction. - -=head1 RETURN VALUES - -RAND_status() and RAND_event() return 1 if the PRNG has been seeded -with enough data, 0 otherwise. - -The other functions do not return values. - -=head1 SEE ALSO - -L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>, -L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> - -=head1 HISTORY - -RAND_seed() and RAND_screen() are available in all versions of SSLeay -and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL -0.9.5, RAND_event() in OpenSSL 0.9.5a. - -=cut diff --git a/openssl/trunk/doc/crypto/RAND_bytes.pod b/openssl/trunk/doc/crypto/RAND_bytes.pod deleted file mode 100644 index ce6329ce..00000000 --- a/openssl/trunk/doc/crypto/RAND_bytes.pod +++ /dev/null @@ -1,47 +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); - - int RAND_pseudo_bytes(unsigned char *buf, int num); - -=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() 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. - -=head1 RETURN VALUES - -RAND_bytes() returns 1 on success, 0 otherwise. The error code can be -obtained by L<ERR_get_error(3)|ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the -bytes generated are cryptographically strong, 0 otherwise. Both -functions return -1 if they are not supported by the current RAND -method. - -=head1 SEE ALSO - -L<rand(3)|rand(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<RAND_add(3)|RAND_add(3)> - -=head1 HISTORY - -RAND_bytes() is available in all versions of SSLeay and OpenSSL. It -has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added -in OpenSSL 0.9.5. - -=cut diff --git a/openssl/trunk/doc/crypto/RAND_cleanup.pod b/openssl/trunk/doc/crypto/RAND_cleanup.pod deleted file mode 100644 index 3a8f0749..00000000 --- a/openssl/trunk/doc/crypto/RAND_cleanup.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -RAND_cleanup - erase the PRNG state - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - void RAND_cleanup(void); - -=head1 DESCRIPTION - -RAND_cleanup() erases the memory used by the PRNG. - -=head1 RETURN VALUE - -RAND_cleanup() returns no value. - -=head1 SEE ALSO - -L<rand(3)|rand(3)> - -=head1 HISTORY - -RAND_cleanup() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/RAND_egd.pod b/openssl/trunk/doc/crypto/RAND_egd.pod deleted file mode 100644 index 62adbe19..00000000 --- a/openssl/trunk/doc/crypto/RAND_egd.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -RAND_egd - 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)|RAND_add(3)> to seed the -OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for -RAND_egd_bytes(path, 255); - -RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>. -It queries B<bytes> bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the -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)|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. The read is performed in -non-blocking mode. - -Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is -available from -http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html . -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)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, -L<RAND_cleanup(3)|RAND_cleanup(3)> - -=head1 HISTORY - -RAND_egd() is available since OpenSSL 0.9.5. - -RAND_egd_bytes() is available since OpenSSL 0.9.6. - -RAND_query_egd_bytes() is available since OpenSSL 0.9.7. - -The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/RAND_load_file.pod b/openssl/trunk/doc/crypto/RAND_load_file.pod deleted file mode 100644 index d8c134e6..00000000 --- a/openssl/trunk/doc/crypto/RAND_load_file.pod +++ /dev/null @@ -1,53 +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. The seed file is $RANDFILE if that environment variable is -set, $HOME/.rnd otherwise. If $HOME is not set either, or B<num> is -too small for the path name, an error occurs. - -RAND_load_file() reads a number of bytes from file B<filename> and -adds them to the PRNG. If B<max_bytes> is non-negative, -up to to B<max_bytes> are read; starting with OpenSSL 0.9.5, -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)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> - -=head1 HISTORY - -RAND_load_file(), RAND_write_file() and RAND_file_name() are available in -all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/RAND_set_rand_method.pod b/openssl/trunk/doc/crypto/RAND_set_rand_method.pod deleted file mode 100644 index c9bb6d9f..00000000 --- a/openssl/trunk/doc/crypto/RAND_set_rand_method.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - 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_SSLeay(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_SSLeay(). - -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 dependant 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 the implementation of RAND_seed(), -RAND_bytes(), RAND_cleanup(), RAND_add(), RAND_pseudo_rand() -and RAND_status(). -Each component may be NULL if the function is not implemented. - -=head1 RETURN VALUES - -RAND_set_rand_method() returns no value. RAND_get_rand_method() and -RAND_SSLeay() return pointers to the respective methods. - -=head1 NOTES - -As of version 0.9.7, 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)|rand(3)>, L<engine(3)|engine(3)> - -=head1 HISTORY - -RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are -available in all versions of OpenSSL. - -In the engine version of version 0.9.6, RAND_set_rand_method() was altered to -take an ENGINE pointer as its argument. As of version 0.9.7, that has been -reverted as the ENGINE API transparently overrides RAND defaults if used, -otherwise RAND API functions work as before. RAND_set_rand_engine() was also -introduced in version 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_blinding_on.pod b/openssl/trunk/doc/crypto/RSA_blinding_on.pod deleted file mode 100644 index fd2c69ab..00000000 --- a/openssl/trunk/doc/crypto/RSA_blinding_on.pod +++ /dev/null @@ -1,43 +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 SEE ALSO - -L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)> - -=head1 HISTORY - -RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_check_key.pod b/openssl/trunk/doc/crypto/RSA_check_key.pod deleted file mode 100644 index a5198f3d..00000000 --- a/openssl/trunk/doc/crypto/RSA_check_key.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -RSA_check_key - validate private RSA keys - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_check_key(RSA *rsa); - -=head1 DESCRIPTION - -This function validates RSA keys. It checks that B<p> and B<q> are -in fact prime, and that B<n = p*q>. - -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>. - -As such, this function can not be used with any arbitrary RSA key object, -even if it is otherwise fit for regular RSA operation. See B<NOTES> for more -information. - -=head1 RETURN VALUE - -RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise. --1 is returned if an error occurs while checking the key. - -If the key is invalid or an error occurred, the reason code can be -obtained using L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 NOTES - -This function does not work on RSA public keys that have only the modulus -and public exponent elements populated. It performs integrity checks on all -the RSA key material, so the RSA key structure must contain all the private -key data too. - -Unlike most other RSA functions, this function does B<not> work -transparently with any underlying ENGINE implementation because it uses the -key data in the RSA structure directly. An ENGINE implementation can -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<rsa(3)|rsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -RSA_check_key() appeared in OpenSSL 0.9.4. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_generate_key.pod b/openssl/trunk/doc/crypto/RSA_generate_key.pod deleted file mode 100644 index 52dbb14a..00000000 --- a/openssl/trunk/doc/crypto/RSA_generate_key.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -RSA_generate_key - generate RSA key pair - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - -=head1 DESCRIPTION - -RSA_generate_key() generates a key pair and returns it in a newly -allocated B<RSA> structure. The pseudo-random number generator must -be seeded prior to calling RSA_generate_key(). - -The modulus size will be B<num> 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<callback> is not B<NULL>, it -will be called as follows: - -=over 4 - -=item * - -While a random prime number is generated, it is called as -described in L<BN_generate_prime(3)|BN_generate_prime(3)>. - -=item * - -When the n-th randomly generated prime is rejected as not -suitable for the key, B<callback(2, n, cb_arg)> is called. - -=item * - -When a random p has been found with p-1 relatively prime to B<e>, -it is called as B<callback(3, 0, cb_arg)>. - -=back - -The process is then repeated for prime q with B<callback(3, 1, cb_arg)>. - -=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)|ERR_get_error(3)>. - -=head1 BUGS - -B<callback(2, x, cb_arg)> 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)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<RSA_free(3)|RSA_free(3)> - -=head1 HISTORY - -The B<cb_arg> argument was added in SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_get_ex_new_index.pod b/openssl/trunk/doc/crypto/RSA_get_ex_new_index.pod deleted file mode 100644 index 46cc8f53..00000000 --- a/openssl/trunk/doc/crypto/RSA_get_ex_new_index.pod +++ /dev/null @@ -1,120 +0,0 @@ -=pod - -=head1 NAME - -RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int RSA_set_ex_data(RSA *r, int idx, void *arg); - - void *RSA_get_ex_data(RSA *r, int idx); - - typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -This has several potential uses, it can be used to cache data associated with -a structure (for example the hash of some part of the structure) or some -additional data (for example a handle to the data in an external library). - -Since the application data can be anything at all it is passed and retrieved -as a B<void *> type. - -The B<RSA_get_ex_new_index()> function is initially called to "register" some -new application specific data. It takes three optional function pointers which -are called when the parent structure (in this case an RSA structure) is -initially created, when it is copied and when it is freed up. If any or all of -these function pointer arguments are not used they should be set to NULL. The -precise manner in which these function pointers are called is described in more -detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer -parameters which will be passed to the supplied functions but which otherwise -have no special meaning. It returns an B<index> which should be stored -(typically in a static variable) and passed used in the B<idx> parameter in -the remaining functions. Each successful call to B<RSA_get_ex_new_index()> -will return an index greater than any previously returned, this is important -because the optional functions are called in order of increasing index value. - -B<RSA_set_ex_data()> is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -B<RSA_get_ex_data()> is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B<RSA_set_ex_data()> call. - -B<new_func()> is called when a structure is initially allocated (for example -with B<RSA_new()>. The parent structure members will not have any meaningful -values at this point. This function will typically be used to allocate any -application specific structure. - -B<free_func()> is called when a structure is being freed up. The dynamic parent -structure members should not be accessed because they will be freed up when -this function is called. - -B<new_func()> and B<free_func()> take the same parameters. B<parent> is a -pointer to the parent RSA structure. B<ptr> is a the application specific data -(this wont be of much use in B<new_func()>. B<ad> is a pointer to the -B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions -B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate -it. The B<idx> parameter is the index: this will be the same value returned by -B<RSA_get_ex_new_index()> when the functions were initially registered. Finally -the B<argl> and B<argp> parameters are the values originally passed to the same -corresponding parameters when B<RSA_get_ex_new_index()> was called. - -B<dup_func()> is called when a structure is being copied. Pointers to the -destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and -B<from> parameters respectively. The B<from_d> parameter is passed a pointer to -the source application data when the function is called, when the function returns -the value is copied to the destination: the application can thus modify the data -pointed to by B<from_d> and have different values in the source and destination. -The B<idx>, B<argl> and B<argp> parameters are the same as those in B<new_func()> -and B<free_func()>. - -=head1 RETURN VALUES - -B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a valid -index value). - -B<RSA_set_ex_data()> returns 1 on success or 0 on failure. - -B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success. - -On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 BUGS - -B<dup_func()> is currently never called. - -The return value of B<new_func()> is ignored. - -The B<new_func()> function isn't very useful because no meaningful values are -present in the parent RSA structure when it is called. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> - -=head1 HISTORY - -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are -available since SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_new.pod b/openssl/trunk/doc/crypto/RSA_new.pod deleted file mode 100644 index 3d15b928..00000000 --- a/openssl/trunk/doc/crypto/RSA_new.pod +++ /dev/null @@ -1,41 +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. - -=head1 RETURN VALUES - -If the allocation fails, RSA_new() returns B<NULL> and sets an error -code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns -a pointer to the newly allocated structure. - -RSA_free() returns no value. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, -L<RSA_generate_key(3)|RSA_generate_key(3)>, -L<RSA_new_method(3)|RSA_new_method(3)> - -=head1 HISTORY - -RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/openssl/trunk/doc/crypto/RSA_padding_add_PKCS1_type_1.pod deleted file mode 100644 index b8f678fe..00000000 --- a/openssl/trunk/doc/crypto/RSA_padding_add_PKCS1_type_1.pod +++ /dev/null @@ -1,124 +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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, -L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> - -=head1 HISTORY - -RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(), -RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(), -RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(), -RSA_padding_add_none() and RSA_padding_check_none() appeared in -SSLeay 0.9.0. - -RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were -added in OpenSSL 0.9.2b. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_print.pod b/openssl/trunk/doc/crypto/RSA_print.pod deleted file mode 100644 index c971e91f..00000000 --- a/openssl/trunk/doc/crypto/RSA_print.pod +++ /dev/null @@ -1,49 +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<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> - -=head1 HISTORY - -RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), -DH_print_fp() are available in all versions of SSLeay and OpenSSL. -DSAparams_print() and DSAparams_print_fp() were added in SSLeay 0.8. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_private_encrypt.pod b/openssl/trunk/doc/crypto/RSA_private_encrypt.pod deleted file mode 100644 index 746a80c7..00000000 --- a/openssl/trunk/doc/crypto/RSA_private_encrypt.pod +++ /dev/null @@ -1,70 +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)|RSA_sign(3)> and L<RSA_verify(3)|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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> - -=head1 HISTORY - -The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_public_encrypt.pod b/openssl/trunk/doc/crypto/RSA_public_encrypt.pod deleted file mode 100644 index ab0fe3b2..00000000 --- a/openssl/trunk/doc/crypto/RSA_public_encrypt.pod +++ /dev/null @@ -1,84 +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)|ERR_get_error(3)>. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<RSA_size(3)|RSA_size(3)> - -=head1 HISTORY - -The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_set_method.pod b/openssl/trunk/doc/crypto/RSA_set_method.pod deleted file mode 100644 index 0a305f6b..00000000 --- a/openssl/trunk/doc/crypto/RSA_set_method.pod +++ /dev/null @@ -1,202 +0,0 @@ -=pod - -=head1 NAME - -RSA_set_default_method, RSA_get_default_method, RSA_set_method, -RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags, -RSA_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_SSLeay(void); - - RSA_METHOD *RSA_null_method(void); - - int RSA_flags(const RSA *rsa); - - RSA *RSA_new_method(RSA_METHOD *method); - -=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_SSLeay(). - -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 dependant 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_FLAG_SIGN_VER - enable rsa_sign and rsa_verify - * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match - */ - int flags; - - char *app_data; /* ?? */ - - /* sign. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - - /* verify. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - - } RSA_METHOD; - -=head1 RETURN VALUES - -RSA_PKCS1_SSLeay(), 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)|ERR_get_error(3)> if the allocation fails. Otherwise -it returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, RSA_METHOD implementations are grouped together with -other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B<ENGINE> -modules. If a default ENGINE is specified for RSA functionality using an -ENGINE API function, that will override any RSA defaults set using the RSA -API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the -recommended way to control default implementations for use in RSA and other -cryptographic algorithms. - -=head1 BUGS - -The behaviour of RSA_flags() is a mis-feature that is left as-is for now -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(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)> - -=head1 HISTORY - -RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8. -RSA_get_default_method(), RSA_set_method() and RSA_get_method() as -well as the rsa_sign and rsa_verify components of RSA_METHOD were -added in OpenSSL 0.9.4. - -RSA_set_default_openssl_method() and RSA_get_default_openssl_method() -replaced RSA_set_default_method() and RSA_get_default_method() -respectively, and RSA_set_method() and RSA_new_method() were altered to use -B<ENGINE>s rather than B<RSA_METHOD>s during development of the engine -version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE -API was restructured so that this change was reversed, and behaviour of the -other functions resembled more closely the previous behaviour. The -behaviour of defaults in the ENGINE API now transparently overrides the -behaviour of defaults in the RSA API without requiring changing these -function prototypes. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_sign.pod b/openssl/trunk/doc/crypto/RSA_sign.pod deleted file mode 100644 index 8553be8e..00000000 --- a/openssl/trunk/doc/crypto/RSA_sign.pod +++ /dev/null @@ -1,62 +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. - -B<type> denotes the message digest algorithm that was used to generate -B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>; -see L<objects(3)|objects(3)> for details. If B<type> is B<NID_md5_sha1>, -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, 0 otherwise. RSA_verify() returns 1 -on successful verification, 0 otherwise. - -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 BUGS - -Certain signatures with an improper algorithm identifier are accepted -for compatibility with SSLeay 0.4.5 :-) - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, -L<rsa(3)|rsa(3)>, L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, -L<RSA_public_decrypt(3)|RSA_public_decrypt(3)> - -=head1 HISTORY - -RSA_sign() and RSA_verify() are available in all versions of SSLeay -and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/openssl/trunk/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod deleted file mode 100644 index e70380bb..00000000 --- a/openssl/trunk/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod +++ /dev/null @@ -1,59 +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)|ERR_get_error(3)>. - -=head1 BUGS - -These functions serve no recognizable purpose. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, -L<RSA_verify(3)|RSA_verify(3)> - -=head1 HISTORY - -RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were -added in SSLeay 0.8. - -=cut diff --git a/openssl/trunk/doc/crypto/RSA_size.pod b/openssl/trunk/doc/crypto/RSA_size.pod deleted file mode 100644 index 5b7f835f..00000000 --- a/openssl/trunk/doc/crypto/RSA_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -RSA_size - get RSA modulus size - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_size(const RSA *rsa); - -=head1 DESCRIPTION - -This function returns the RSA modulus size in bytes. It can be used to -determine how much memory must be allocated for an RSA encrypted -value. - -B<rsa-E<gt>n> must not be B<NULL>. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)> - -=head1 HISTORY - -RSA_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/SMIME_read_PKCS7.pod b/openssl/trunk/doc/crypto/SMIME_read_PKCS7.pod deleted file mode 100644 index ffafa378..00000000 --- a/openssl/trunk/doc/crypto/SMIME_read_PKCS7.pod +++ /dev/null @@ -1,71 +0,0 @@ -=pod - -=head1 NAME - -SMIME_read_PKCS7 - parse S/MIME message. - -=head1 SYNOPSIS - -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)|ERR_get_error(3)>, L<PKCS7_type(3)|PKCS7_type(3)> -L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -SMIME_read_PKCS7() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/trunk/doc/crypto/SMIME_write_PKCS7.pod b/openssl/trunk/doc/crypto/SMIME_write_PKCS7.pod deleted file mode 100644 index 61945b38..00000000 --- a/openssl/trunk/doc/crypto/SMIME_write_PKCS7.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format. - -=head1 SYNOPSIS - -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 cleartext signing (B<multipart/signed>) is -being used then the signed data 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_PARTSIGN> flag is set the signed data is finalized -and output along with the content. This flag should only be set -if B<PKCS7_DETACHED> is also set and the previous call to PKCS7_sign() -also set these flags. - -If cleartext signing is being used and B<PKCS7_PARTSIGN> 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. - -=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)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -SMIME_write_PKCS7() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/trunk/doc/crypto/X509_NAME_ENTRY_get_object.pod b/openssl/trunk/doc/crypto/X509_NAME_ENTRY_get_object.pod deleted file mode 100644 index 11b35f6f..00000000 --- a/openssl/trunk/doc/crypto/X509_NAME_ENTRY_get_object.pod +++ /dev/null @@ -1,72 +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 - -ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne); -ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne); - -int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, ASN1_OBJECT *obj); -int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len); - -X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len); -X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type,unsigned char *bytes, int len); -X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len); - -=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 RETURN VALUES - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, -L<OBJ_nid2obj(3),OBJ_nid2obj(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/X509_NAME_add_entry_by_txt.pod b/openssl/trunk/doc/crypto/X509_NAME_add_entry_by_txt.pod deleted file mode 100644 index e2ab4b0d..00000000 --- a/openssl/trunk/doc/crypto/X509_NAME_add_entry_by_txt.pod +++ /dev/null @@ -1,114 +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 - -int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set); - -int X509_NAME_add_entry_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set); - -int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set); - -int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set); - -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 recommened 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, MBSTRING_ASC, - "C", "UK", -1, -1, 0)) - /* Error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "O", "Disorganized Organization", -1, -1, 0)) - /* Error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "CN", "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)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/trunk/doc/crypto/X509_NAME_get_index_by_NID.pod b/openssl/trunk/doc/crypto/X509_NAME_get_index_by_NID.pod deleted file mode 100644 index 333323d7..00000000 --- a/openssl/trunk/doc/crypto/X509_NAME_get_index_by_NID.pod +++ /dev/null @@ -1,106 +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 - -int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos); -int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos); - -int X509_NAME_entry_count(X509_NAME *name); -X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc); - -int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len); -int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len); - -=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. - -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 muticharacter 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. - -=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_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)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/X509_NAME_print_ex.pod b/openssl/trunk/doc/crypto/X509_NAME_print_ex.pod deleted file mode 100644 index 919b9089..00000000 --- a/openssl/trunk/doc/crypto/X509_NAME_print_ex.pod +++ /dev/null @@ -1,105 +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, X509_NAME *nm, int indent, unsigned long flags); - int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags); - char * X509_NAME_oneline(X509_NAME *a,char *buf,int size); - int X509_NAME_print(BIO *bp, X509_NAME *name, int obase); - -=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)|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 it 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 is 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)|ASN1_STRING_print_ex(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/X509_new.pod b/openssl/trunk/doc/crypto/X509_new.pod deleted file mode 100644 index fd5fc65c..00000000 --- a/openssl/trunk/doc/crypto/X509_new.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -X509_new, X509_free - X509 certificate ASN1 allocation functions - -=head1 SYNOPSIS - - X509 *X509_new(void); - void X509_free(X509 *a); - -=head1 DESCRIPTION - -The X509 ASN1 allocation routines, allocate and free an -X509 structure, which represents an X509 certificate. - -X509_new() allocates and initializes a X509 structure. - -X509_free() frees up the B<X509> structure B<a>. - -=head1 RETURN VALUES - -If the allocation fails, X509_new() returns B<NULL> and sets an error -code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. -Otherwise it returns a pointer to the newly allocated structure. - -X509_free() returns no value. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -X509_new() and X509_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/bio.pod b/openssl/trunk/doc/crypto/bio.pod deleted file mode 100644 index f9239226..00000000 --- a/openssl/trunk/doc/crypto/bio.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -bio - I/O abstraction - -=head1 SYNOPSIS - - #include <openssl/bio.h> - -TBA - - -=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). - -=head1 SEE ALSO - -L<BIO_ctrl(3)|BIO_ctrl(3)>, -L<BIO_f_base64(3)|BIO_f_base64(3)>, L<BIO_f_buffer(3)|BIO_f_buffer(3)>, -L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>, -L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>, -L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>, -L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>, -L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>, -L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>, -L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, -L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>, -L<BIO_set_callback(3)|BIO_set_callback(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)> diff --git a/openssl/trunk/doc/crypto/blowfish.pod b/openssl/trunk/doc/crypto/blowfish.pod deleted file mode 100644 index 5b2d274c..00000000 --- a/openssl/trunk/doc/crypto/blowfish.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -blowfish, 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)|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)|EVP_EncryptInit(3)> etc. instead of calling the -blowfish functions directly. - -=head1 SEE ALSO - -L<des_modes(7)|des_modes(7)> - -=head1 HISTORY - -The Blowfish functions are available in all versions of SSLeay and OpenSSL. - -=cut - diff --git a/openssl/trunk/doc/crypto/bn.pod b/openssl/trunk/doc/crypto/bn.pod deleted file mode 100644 index cd2f8e50..00000000 --- a/openssl/trunk/doc/crypto/bn.pod +++ /dev/null @@ -1,181 +0,0 @@ -=pod - -=head1 NAME - -bn - multiprecision integer arithmetics - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_new(void); - void BN_free(BIGNUM *a); - void BN_init(BIGNUM *); - void BN_clear(BIGNUM *a); - void BN_clear_free(BIGNUM *a); - - BN_CTX *BN_CTX_new(void); - void BN_CTX_init(BN_CTX *c); - void BN_CTX_free(BN_CTX *c); - - BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); - BIGNUM *BN_dup(const BIGNUM *a); - - BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); - - int BN_num_bytes(const BIGNUM *a); - int BN_num_bits(const BIGNUM *a); - int BN_num_bits_word(BN_ULONG w); - - void BN_set_negative(BIGNUM *a, int n); - int BN_is_negative(const BIGNUM *a); - - int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); - int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, - BN_CTX *ctx); - int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); - int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx); - int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - - int BN_add_word(BIGNUM *a, BN_ULONG w); - int BN_sub_word(BIGNUM *a, BN_ULONG w); - int BN_mul_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); - - int BN_cmp(BIGNUM *a, BIGNUM *b); - int BN_ucmp(BIGNUM *a, BIGNUM *b); - int BN_is_zero(BIGNUM *a); - int BN_is_one(BIGNUM *a); - int BN_is_word(BIGNUM *a, BN_ULONG w); - int BN_is_odd(BIGNUM *a); - - int BN_zero(BIGNUM *a); - int BN_one(BIGNUM *a); - const BIGNUM *BN_value_one(void); - int BN_set_word(BIGNUM *a, unsigned long w); - unsigned long BN_get_word(BIGNUM *a); - - int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_rand_range(BIGNUM *rnd, BIGNUM *range); - int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); - - BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, - BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); - int BN_is_prime(const BIGNUM *p, int nchecks, - void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); - - int BN_set_bit(BIGNUM *a, int n); - int BN_clear_bit(BIGNUM *a, int n); - int BN_is_bit_set(const BIGNUM *a, int n); - int BN_mask_bits(BIGNUM *a, int n); - int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); - int BN_lshift1(BIGNUM *r, BIGNUM *a); - int BN_rshift(BIGNUM *r, BIGNUM *a, int n); - int BN_rshift1(BIGNUM *r, BIGNUM *a); - - int BN_bn2bin(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); - char *BN_bn2hex(const BIGNUM *a); - char *BN_bn2dec(const BIGNUM *a); - int BN_hex2bn(BIGNUM **a, const char *str); - int BN_dec2bn(BIGNUM **a, const char *str); - int BN_print(BIO *fp, const BIGNUM *a); - int BN_print_fp(FILE *fp, const BIGNUM *a); - int BN_bn2mpi(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); - - BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, - BN_CTX *ctx); - - BN_RECP_CTX *BN_RECP_CTX_new(void); - void BN_RECP_CTX_init(BN_RECP_CTX *recp); - void BN_RECP_CTX_free(BN_RECP_CTX *recp); - int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_RECP_CTX *recp, BN_CTX *ctx); - - BN_MONT_CTX *BN_MONT_CTX_new(void); - void BN_MONT_CTX_init(BN_MONT_CTX *ctx); - void BN_MONT_CTX_free(BN_MONT_CTX *mont); - int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); - BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); - int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_MONT_CTX *mont, BN_CTX *ctx); - int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - - BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, - BIGNUM *mod); - void BN_BLINDING_free(BN_BLINDING *b); - int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); - int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, - BN_CTX *ctx); - int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b, - BN_CTX *ctx); - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); - void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); - BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, - const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, - int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), - BN_MONT_CTX *m_ctx); - -=head1 DESCRIPTION - -This library performs arithmetic operations on integers of arbitrary -size. It was written for use in public key cryptography, such as RSA -and Diffie-Hellman. - -It uses dynamic memory allocation for storing its data structures. -That means that there is no limit on the size of the numbers -manipulated by these functions, but return values must always be -checked in case a memory allocation error has occurred. - -The basic object in this library is a B<BIGNUM>. It is used to hold a -single large integer. This type should be considered opaque and fields -should not be modified or accessed directly. - -The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; -L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. -Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> -describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of -random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime -numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion -of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. - -=head1 SEE ALSO - -L<bn_internal(3)|bn_internal(3)>, -L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, -L<BN_copy(3)|BN_copy(3)>, L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, -L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, -L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, -L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, -L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, -L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>, -L<BN_BLINDING_new(3)|BN_BLINDING_new(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/bn_internal.pod b/openssl/trunk/doc/crypto/bn_internal.pod deleted file mode 100644 index 89191467..00000000 --- a/openssl/trunk/doc/crypto/bn_internal.pod +++ /dev/null @@ -1,226 +0,0 @@ -=pod - -=head1 NAME - -bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, -bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, -bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, -bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, -bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, -bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, -bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low - BIGNUM -library internal functions - -=head1 SYNOPSIS - - BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); - BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, - BN_ULONG w); - void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); - BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); - BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - - void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); - void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); - - int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); - - void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, - int nb); - void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); - void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, - int dna,int dnb,BN_ULONG *tmp); - void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n, int tna,int tnb, BN_ULONG *tmp); - void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n2, BN_ULONG *tmp); - void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, - int n2, BN_ULONG *tmp); - - void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); - void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); - - void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); - - BIGNUM *bn_expand(BIGNUM *a, int bits); - BIGNUM *bn_wexpand(BIGNUM *a, int n); - BIGNUM *bn_expand2(BIGNUM *a, int n); - void bn_fix_top(BIGNUM *a); - - void bn_check_top(BIGNUM *a); - void bn_print(BIGNUM *a); - void bn_dump(BN_ULONG *d, int n); - void bn_set_max(BIGNUM *a); - void bn_set_high(BIGNUM *r, BIGNUM *a, int n); - void bn_set_low(BIGNUM *r, BIGNUM *a, int n); - -=head1 DESCRIPTION - -This page documents the internal functions used by the OpenSSL -B<BIGNUM> implementation. They are described here to facilitate -debugging and extending the library. They are I<not> to be used by -applications. - -=head2 The BIGNUM structure - - typedef struct bignum_st - { - int top; /* number of words used in d */ - BN_ULONG *d; /* pointer to an array containing the integer value */ - int max; /* size of the d array */ - int neg; /* sign */ - } BIGNUM; - -The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>), -least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits -in size, depending on the 'number of bits' (B<BITS2>) specified in -C<openssl/bn.h>. - -B<max> is the size of the B<d> array that has been allocated. B<top> -is the number of words being used, so for a value of 4, bn.d[0]=4 and -bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is -B<0>, the B<d> field can be B<NULL> and B<top> == B<0>. - -Various routines in this library require the use of temporary -B<BIGNUM> variables during their execution. Since dynamic memory -allocation to create B<BIGNUM>s is rather expensive when used in -conjunction with repeated subroutine calls, the B<BN_CTX> structure is -used. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see -L<BN_CTX_start(3)|BN_CTX_start(3)>. - -=head2 Low-level arithmetic operations - -These functions are implemented in C and for several platforms in -assembly language: - -bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word -arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result -in B<rp>, and returns the high word (carry). - -bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> -word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places -the result in B<rp>, and returns the high word (carry). - -bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array -B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap> -word-wise, and places the low and high bytes of the result in B<rp>. - -bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>,B<l>) -by B<d> and returns the result. - -bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the -result in B<rp>, and returns the high word (carry). - -bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the -result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0 -otherwise). - -bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. - -bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. - -The following functions are implemented in C: - -bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a> -and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and -less than B<b>. - -bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na> -word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word -array B<r>. It computes B<a>*B<b> and places the result in B<r>. - -bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word -arrays B<r>, B<a> and B<b>. It computes the B<n> low words of -B<a>*B<b> and places the result in B<r>. - -bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates -on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb> -(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2> -word arrays B<r> and B<t>. B<n2> must be a power of 2. It computes -B<a>*B<b> and places the result in B<r>. - -bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>) -operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and -B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>. - -bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a> -and B<b>. - -bn_mul_high(B<r>, B<a>, B<b>, B<l>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r>, B<a>, B<b> and B<l> (?) and the 3*B<n2> word -array B<tmp>. - -BN_mul() calls bn_mul_normal(), or an optimized implementation if the -factors have the same size: bn_mul_comba8() is used if they are 8 -words long, bn_mul_recursive() if they are larger than -B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word -size, and bn_mul_part_recursive() for others that are larger than -B<BN_MULL_SIZE_NORMAL>. - -bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array -B<a> and the 2*B<n> word arrays B<tmp> and B<r>. - -The implementations use the following macros which, depending on the -architecture, may use "long long" C operations or inline assembler. -They are defined in C<bn_lcl.h>. - -mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the -low word of the result in B<r> and the high word in B<c>. - -mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and -places the low word of the result in B<r> and the high word in B<c>. - -sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word -of the result in B<r0> and the high word in B<r1>. - -=head2 Size changes - -bn_expand() ensures that B<b> has enough space for a B<bits> bit -number. bn_wexpand() ensures that B<b> has enough space for an -B<n> word number. If the number has to be expanded, both macros -call bn_expand2(), which allocates a new B<d> array and copies the -data. They return B<NULL> on error, B<b> otherwise. - -The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most -significant non-zero word plus one when B<a> has shrunk. - -=head2 Debugging - -bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top -E<lt>= (a)-E<gt>max)>. A violation will cause the program to abort. - -bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d> -(in reverse order, i.e. most significant word first) to stderr. - -bn_set_max() makes B<a> a static number with a B<max> of its current size. -This is used by bn_set_low() and bn_set_high() to make B<r> a read-only -B<BIGNUM> that contains the B<n> low or high words of B<a>. - -If B<BN_DEBUG> is not defined, bn_check_top(), bn_print(), bn_dump() -and bn_set_max() are defined as empty macros. - -=head1 SEE ALSO - -L<bn(3)|bn(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/buffer.pod b/openssl/trunk/doc/crypto/buffer.pod deleted file mode 100644 index 781f5b11..00000000 --- a/openssl/trunk/doc/crypto/buffer.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple -character arrays structure - -=head1 SYNOPSIS - - #include <openssl/buffer.h> - - BUF_MEM *BUF_MEM_new(void); - - void BUF_MEM_free(BUF_MEM *a); - - int BUF_MEM_grow(BUF_MEM *str, int len); - - char * BUF_strdup(const char *str); - -=head1 DESCRIPTION - -The buffer library handles simple character arrays. Buffers are used for -various purposes in the library, most notably memory BIOs. - -The library uses the BUF_MEM structure defined in buffer.h: - - typedef struct buf_mem_st - { - int length; /* current number of bytes */ - char *data; - int max; /* size of buffer */ - } BUF_MEM; - -B<length> is the current size of the buffer in bytes, B<max> is the amount of -memory allocated to the buffer. There are three functions which handle these -and one "miscellaneous" function. - -BUF_MEM_new() allocates a new buffer of zero size. - -BUF_MEM_free() frees up an already existing buffer. The data is zeroed -before freeing up in case the buffer contains sensitive data. - -BUF_MEM_grow() changes the size of an already existing buffer to -B<len>. Any data already in the buffer is preserved if it increases in -size. - -BUF_strdup() copies a null terminated string into a block of allocated -memory and returns a pointer to the allocated block. -Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so -should be used in preference to the standard library strdup() because it can -be used for memory leak checking or replacing the malloc() function. - -The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free() -function. - -=head1 RETURN VALUES - -BUF_MEM_new() returns the buffer or NULL on error. - -BUF_MEM_free() has no return value. - -BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>). - -=head1 SEE ALSO - -L<bio(3)|bio(3)> - -=head1 HISTORY - -BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all -versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. - -=cut diff --git a/openssl/trunk/doc/crypto/crypto.pod b/openssl/trunk/doc/crypto/crypto.pod deleted file mode 100644 index 7a527992..00000000 --- a/openssl/trunk/doc/crypto/crypto.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -crypto - OpenSSL cryptographic library - -=head1 SYNOPSIS - -=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. - -=head1 OVERVIEW - -B<libcrypto> consists of a number of sub-libraries that implement the -individual algorithms. - -The functionality includes symmetric encryption, public key -cryptography and key agreement, certificate handling, cryptographic -hash functions and a cryptographic pseudo-random number generator. - -=over 4 - -=item SYMMETRIC CIPHERS - -L<blowfish(3)|blowfish(3)>, L<cast(3)|cast(3)>, L<des(3)|des(3)>, -L<idea(3)|idea(3)>, L<rc2(3)|rc2(3)>, L<rc4(3)|rc4(3)>, L<rc5(3)|rc5(3)> - -=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT - -L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rsa(3)|rsa(3)> - -=item CERTIFICATES - -L<x509(3)|x509(3)>, L<x509v3(3)|x509v3(3)> - -=item AUTHENTICATION CODES, HASH FUNCTIONS - -L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md4(3)|md4(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)> - -=item AUXILIARY FUNCTIONS - -L<err(3)|err(3)>, L<threads(3)|threads(3)>, L<rand(3)|rand(3)>, -L<OPENSSL_VERSION_NUMBER(3)|OPENSSL_VERSION_NUMBER(3)> - -=item INPUT/OUTPUT, DATA ENCODING - -L<asn1(3)|asn1(3)>, L<bio(3)|bio(3)>, L<evp(3)|evp(3)>, L<pem(3)|pem(3)>, -L<pkcs7(3)|pkcs7(3)>, L<pkcs12(3)|pkcs12(3)> - -=item INTERNAL FUNCTIONS - -L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<lhash(3)|lhash(3)>, -L<objects(3)|objects(3)>, L<stack(3)|stack(3)>, -L<txt_db(3)|txt_db(3)> - -=back - -=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, 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 SEE ALSO - -L<openssl(1)|openssl(1)>, L<ssl(3)|ssl(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_ASN1_OBJECT.pod b/openssl/trunk/doc/crypto/d2i_ASN1_OBJECT.pod deleted file mode 100644 index 45bb1849..00000000 --- a/openssl/trunk/doc/crypto/d2i_ASN1_OBJECT.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions - -=head1 SYNOPSIS - - #include <openssl/objects.h> - - ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length); - int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an ASN1 OBJECT IDENTIFIER. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_DHparams.pod b/openssl/trunk/doc/crypto/d2i_DHparams.pod deleted file mode 100644 index 1e98aebe..00000000 --- a/openssl/trunk/doc/crypto/d2i_DHparams.pod +++ /dev/null @@ -1,30 +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. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_DSAPublicKey.pod b/openssl/trunk/doc/crypto/d2i_DSAPublicKey.pod deleted file mode 100644 index 22c1b50f..00000000 --- a/openssl/trunk/doc/crypto/d2i_DSAPublicKey.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, -d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding -and parsing functions. - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/x509.h> - - DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length); - - int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAparams(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length); - - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - -=head1 DESCRIPTION - -d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key -components structure. - -d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key -components. - -d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using -a B<Dss-Parms> structure as defined in RFC2459. - -d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a -B<Dss-Sig-Value> structure as defined in RFC2459. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 NOTES - -The B<DSA> structure passed to the private key encoding functions should have -all the private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey> -functions when encoding public keys because they use a standard format. - -The B<DSAPublicKey> functions use an non standard format the actual data encoded -depends on the value of the B<write_params> field of the B<a> key parameter. -If B<write_params> is zero then only the B<pub_key> field is encoded as an -B<INTEGER>. If B<write_params> is 1 then a B<SEQUENCE> consisting of the -B<p>, B<q>, B<g> and B<pub_key> respectively fields are encoded. - -The B<DSAPrivateKey> functions also use a non standard structure consiting -consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and -B<priv_key> fields respectively. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_PKCS8PrivateKey.pod b/openssl/trunk/doc/crypto/d2i_PKCS8PrivateKey.pod deleted file mode 100644 index a54b7790..00000000 --- a/openssl/trunk/doc/crypto/d2i_PKCS8PrivateKey.pod +++ /dev/null @@ -1,56 +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 the L<pem(3)|pem(3)> manual page. - -=head1 NOTES - -Before using these functions L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> -should be called to initialize the internal algorithm lookup tables otherwise errors about -unknown algorithms will occur if an attempt is made to decrypt a private key. - -These functions are currently the only way to store encrypted private keys using DER format. - -Currently all the functions use BIOs or FILE pointers, there are no functions which -work directly on memory: this can be readily worked around by converting the buffers -to memory BIOs, see L<BIO_s_mem(3)|BIO_s_mem(3)> for details. - -=head1 SEE ALSO - -L<pem(3)|pem(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_RSAPublicKey.pod b/openssl/trunk/doc/crypto/d2i_RSAPublicKey.pod deleted file mode 100644 index 279b29c8..00000000 --- a/openssl/trunk/doc/crypto/d2i_RSAPublicKey.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, -d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, -d2i_Netscape_RSA - RSA public and private key encoding functions. - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - #include <openssl/x509.h> - - RSA * d2i_RSAPublicKey(RSA **a, unsigned char **pp, long length); - - int i2d_RSAPublicKey(RSA *a, unsigned char **pp); - - RSA * d2i_RSA_PUBKEY(RSA **a, unsigned char **pp, long length); - - int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); - - RSA * d2i_RSAPrivateKey(RSA **a, unsigned char **pp, long length); - - int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); - - int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); - - RSA * d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)()); - -=head1 DESCRIPTION - -d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 RSAPublicKey -structure. - -d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 RSAPrivateKey -structure. - -d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in -NET format. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 NOTES - -The B<RSA> structure passed to the private key encoding functions should have -all the PKCS#1 private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The NET format functions are present to provide compatibility with certain very -old software. This format has some severe security weaknesses and should be -avoided if possible. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_X509.pod b/openssl/trunk/doc/crypto/d2i_X509.pod deleted file mode 100644 index 5bfa18af..00000000 --- a/openssl/trunk/doc/crypto/d2i_X509.pod +++ /dev/null @@ -1,231 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, -i2d_X509_fp - X509 encode and decode functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509 *d2i_X509(X509 **px, const unsigned char **in, int len); - int i2d_X509(X509 *x, unsigned char **out); - - X509 *d2i_X509_bio(BIO *bp, X509 **x); - X509 *d2i_X509_fp(FILE *fp, X509 **x); - - int i2d_X509_bio(X509 *x, BIO *bp); - int i2d_X509_fp(X509 *x, FILE *fp); - -=head1 DESCRIPTION - -The X509 encode and decode routines encode and parse an -B<X509> structure, which represents an X509 certificate. - -d2i_X509() attempts to decode B<len> bytes at B<*in>. If -successful a pointer to the B<X509> structure is returned. If an error -occurred then B<NULL> is returned. If B<px> is not B<NULL> then the -returned structure is written to B<*px>. If B<*px> is not B<NULL> -then it is assumed that B<*px> contains a valid B<X509> -structure and an attempt is made to reuse it. If the call is -successful B<*in> is incremented to the byte following the -parsed data. - -i2d_X509() encodes the structure pointed to by B<x> into DER format. -If B<out> is not B<NULL> is writes the DER encoded data to the buffer -at B<*out>, and increments it to point after the data just written. -If the return value is negative an error occurred, otherwise it -returns the length of the encoded data. - -For OpenSSL 0.9.7 and later if B<*out> is B<NULL> memory will be -allocated for a buffer and the encoded data written to it. In this -case B<*out> is not incremented and it points to the start of the -data just written. - -d2i_X509_bio() is similar to d2i_X509() except it attempts -to parse data from BIO B<bp>. - -d2i_X509_fp() is similar to d2i_X509() except it attempts -to parse data from FILE pointer B<fp>. - -i2d_X509_bio() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_X509_fp() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -=head1 NOTES - -The letters B<i> and B<d> in for example B<i2d_X509> stand for -"internal" (that is an internal C structure) and "DER". So that -B<i2d_X509> converts from internal to DER. - -The functions can also understand B<BER> forms. - -The actual X509 structure passed to i2d_X509() must be a valid -populated B<X509> structure it can B<not> simply be fed with an -empty structure such as that returned by X509_new(). - -The encoded data is in binary form and may contain embedded zeroes. -Therefore any FILE pointers or BIOs should be opened in binary mode. -Functions such as B<strlen()> will B<not> return the correct length -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 the auto increment behaviour is to reflect a typical -usage of ASN1 functions: after one structure is encoded or decoded -another will processed after it. - -=head1 EXAMPLES - -Allocate and encode the DER encoding of an X509 structure: - - int len; - unsigned char *buf, *p; - - len = i2d_X509(x, NULL); - - buf = OPENSSL_malloc(len); - - if (buf == NULL) - /* error */ - - p = buf; - - i2d_X509(x, &p); - -If you are using OpenSSL 0.9.7 or later then this can be -simplified to: - - - 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; - - /* Something to setup buf and len */ - - p = buf; - - x = d2i_X509(NULL, &p, len); - - if (x == NULL) - /* Some error */ - -Alternative technique: - - X509 *x; - - unsigned char *buf, *p; - - int len; - - /* Something to setup buf and len */ - - p = buf; - - x = NULL; - - if(!d2i_X509(&x, &p, len)) - /* Some error */ - - -=head1 WARNINGS - -The use of temporary variable is mandatory. A common -mistake is to attempt to use a buffer directly as follows: - - int len; - unsigned char *buf; - - len = i2d_X509(x, NULL); - - buf = OPENSSL_malloc(len); - - if (buf == NULL) - /* error */ - - i2d_X509(x, &buf); - - /* Other stuff ... */ - - OPENSSL_free(buf); - -This code will result in B<buf> apparently containing garbage because -it was incremented after the call to point after the data just written. -Also B<buf> will no longer contain the pointer allocated by B<OPENSSL_malloc()> -and the subsequent call to B<OPENSSL_free()> may well crash. - -The auto allocation feature (setting buf to NULL) only works on OpenSSL -0.9.7 and later. Attempts to use it on earlier versions will typically -cause a segmentation violation. - -Another trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>: - - X509 *x; - - if (!d2i_X509(&x, &p, len)) - /* Some error */ - -This will probably crash somewhere in B<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_X509() when -B<*px> is valid is broken and some parts of the reused structure may -persist if they are not present in the new one. As a result the use -of this "reuse" behaviour is strongly discouraged. - -i2d_X509() will not return an error in many versions of OpenSSL, -if mandatory fields are not initialized due to a programming error -then the encoded structure may contain invalid data or omit the -fields entirely and will not be parsed by d2i_X509(). This may be -fixed in future so code should not assume that i2d_X509() will -always succeed. - -=head1 RETURN VALUES - -d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure -or B<NULL> if an error occurs. The error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -i2d_X509(), i2d_X509_bio() and i2d_X509_fp() return a the number of bytes -successfully encoded or a negative value if an error occurs. The error code -can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -i2d_X509_bio() and i2d_X509_fp() returns 1 for success and 0 if an error -occurs The error code can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp -are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_X509_ALGOR.pod b/openssl/trunk/doc/crypto/d2i_X509_ALGOR.pod deleted file mode 100644 index 9e5cd92c..00000000 --- a/openssl/trunk/doc/crypto/d2i_X509_ALGOR.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length); - int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an B<X509_ALGOR> structure which is -equivalent to the B<AlgorithmIdentifier> structure. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_X509_CRL.pod b/openssl/trunk/doc/crypto/d2i_X509_CRL.pod deleted file mode 100644 index e7295a5d..00000000 --- a/openssl/trunk/doc/crypto/d2i_X509_CRL.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_509_CRL_fp, -i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_CRL *d2i_X509_CRL(X509_CRL **a, const unsigned char **pp, long length); - int i2d_X509_CRL(X509_CRL *a, unsigned char **pp); - - X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x); - X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x); - - int i2d_X509_CRL_bio(X509_CRL *x, BIO *bp); - int i2d_X509_CRL_fp(X509_CRL *x, FILE *fp); - -=head1 DESCRIPTION - -These functions decode and encode an X509 CRL (certificate revocation -list). - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_X509_NAME.pod b/openssl/trunk/doc/crypto/d2i_X509_NAME.pod deleted file mode 100644 index 343ffe15..00000000 --- a/openssl/trunk/doc/crypto/d2i_X509_NAME.pod +++ /dev/null @@ -1,31 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length); - int i2d_X509_NAME(X509_NAME *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an B<X509_NAME> structure which is the -the same as the B<Name> type defined in RFC2459 (and elsewhere) and used -for example in certificate subject and issuer names. - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_X509_REQ.pod b/openssl/trunk/doc/crypto/d2i_X509_REQ.pod deleted file mode 100644 index ae32a389..00000000 --- a/openssl/trunk/doc/crypto/d2i_X509_REQ.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp, -i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_REQ *d2i_X509_REQ(X509_REQ **a, const unsigned char **pp, long length); - int i2d_X509_REQ(X509_REQ *a, unsigned char **pp); - - X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x); - X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x); - - int i2d_X509_REQ_bio(X509_REQ *x, BIO *bp); - int i2d_X509_REQ_fp(X509_REQ *x, FILE *fp); - -=head1 DESCRIPTION - -These functions decode and encode a PKCS#10 certificate request. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/d2i_X509_SIG.pod b/openssl/trunk/doc/crypto/d2i_X509_SIG.pod deleted file mode 100644 index e48fd79a..00000000 --- a/openssl/trunk/doc/crypto/d2i_X509_SIG.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length); - int i2d_X509_SIG(X509_SIG *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an X509_SIG structure which is -equivalent to the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/trunk/doc/crypto/des.pod b/openssl/trunk/doc/crypto/des.pod deleted file mode 100644 index 6f0cf1cc..00000000 --- a/openssl/trunk/doc/crypto/des.pod +++ /dev/null @@ -1,358 +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_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, -DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, -DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption - -=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_cbcm_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *ks1, DES_key_schedule *ks2, - DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2, - int enc); - void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, - 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); - - int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched, - DES_cblock *iv); - int DES_enc_write(int fd, const void *buf, int len, - DES_key_schedule *sched, DES_cblock *iv); - -=head1 DESCRIPTION - -This library contains a fast implementation of the DES encryption -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)|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 is the passed key is a weak key, 0 if it -is ok. The probability that a randomly generated key is weak is -1/2^52, so it is not really worth checking for them. - -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 -really 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)|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 emulates the normal non-thread safe semantics -of crypt(3). - -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. - -DES_enc_read() is used to read I<len> bytes from file descriptor -I<fd> into buffer I<buf>. The data being read from I<fd> is assumed to -have come from DES_enc_write() and is decrypted using I<sched> for -the key schedule and I<iv> for the initial vector. - -B<Warning:> The data format used by DES_enc_write() and DES_enc_read() -has a cryptographic weakness: When asked to write more than MAXWRITE -bytes, DES_enc_write() will split the data into several chunks that -are all encrypted using the same IV. So don't use these functions -unless you are sure you know what you do (in which case you might not -want to use them anyway). They cannot handle non-blocking sockets. -DES_enc_read() uses an internal state and thus cannot be used on -multiple files. - -I<DES_rw_mode> is used to specify the encryption mode to use with -DES_enc_read() and DES_end_write(). If set to I<DES_PCBC_MODE> (the -default), DES_pcbc_encrypt is used. If set to I<DES_CBC_MODE> -DES_cbc_encrypt is used. - -=head1 NOTES - -Single-key DES is insecure due to its short key size. ECB mode is -not suitable for most applications; see L<des_modes(7)|des_modes(7)>. - -The L<evp(3)|evp(3)> library provides higher-level encryption functions. - -=head1 BUGS - -DES_3cbc_encrypt() is flawed and must not be used in applications. - -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 CONFORMING TO - -ANSI X3.106 - -The B<des> library was written to be source code compatible with -the MIT Kerberos library. - -=head1 SEE ALSO - -crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)> - -=head1 HISTORY - -In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid -clashes with older versions of libdes. Compatibility des_ functions -are provided for a short while, as well as crypt(). -Declarations for these are in <openssl/des_old.h>. There is no DES_ -variant for des_random_seed(). -This will happen to other functions -as well if they are deemed redundant (des_random_seed() just calls -RAND_seed() and is present for backward compatibility only), buggy or -already scheduled for removal. - -des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), -des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(), -des_quad_cksum(), des_random_key() and des_string_to_key() -are available in the MIT Kerberos library; -des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() -are available in newer versions of that library. - -des_set_key_checked() and des_set_key_unchecked() were added in -OpenSSL 0.9.5. - -des_generate_random_block(), des_init_random_number_generator(), -des_new_random_key(), des_set_random_generator_seed() and -des_set_sequence_number() and des_rand_data() are used in newer -versions of Kerberos but are not implemented here. - -des_random_key() generated cryptographically weak random data in -SSLeay and in OpenSSL prior version 0.9.5, as well as in the original -MIT library. - -=head1 AUTHOR - -Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/openssl/trunk/doc/crypto/des_modes.pod b/openssl/trunk/doc/crypto/des_modes.pod deleted file mode 100644 index 02664036..00000000 --- a/openssl/trunk/doc/crypto/des_modes.pod +++ /dev/null @@ -1,255 +0,0 @@ -=pod - -=for comment openssl_manual_section:7 - -=head1 NAME - -Modes of DES - 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)|blowfish(3)>, L<des(3)|des(3)>, L<idea(3)|idea(3)>, -L<rc2(3)|rc2(3)> - -=cut - diff --git a/openssl/trunk/doc/crypto/dh.pod b/openssl/trunk/doc/crypto/dh.pod deleted file mode 100644 index c3ccd062..00000000 --- a/openssl/trunk/doc/crypto/dh.pod +++ /dev/null @@ -1,78 +0,0 @@ -=pod - -=head1 NAME - -dh - Diffie-Hellman key agreement - -=head1 SYNOPSIS - - #include <openssl/dh.h> - #include <openssl/engine.h> - - DH * DH_new(void); - void DH_free(DH *dh); - - int DH_size(const DH *dh); - - DH * DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - int DH_check(const DH *dh, int *codes); - - int DH_generate_key(DH *dh); - int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); - - void DH_set_default_method(const DH_METHOD *meth); - const DH_METHOD *DH_get_default_method(void); - int DH_set_method(DH *dh, const DH_METHOD *meth); - DH *DH_new_method(ENGINE *engine); - const DH_METHOD *DH_OpenSSL(void); - - int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DH_set_ex_data(DH *d, int idx, char *arg); - char *DH_get_ex_data(DH *d, int idx); - - DH * d2i_DHparams(DH **a, unsigned char **pp, long length); - int i2d_DHparams(const DH *a, unsigned char **pp); - - int DHparams_print_fp(FILE *fp, const DH *x); - int DHparams_print(BIO *bp, const DH *x); - -=head1 DESCRIPTION - -These functions implement the Diffie-Hellman key agreement protocol. -The generation of shared DH parameters is described in -L<DH_generate_parameters(3)|DH_generate_parameters(3)>; L<DH_generate_key(3)|DH_generate_key(3)> describes how -to perform a key agreement. - -The B<DH> structure consists of several BIGNUM components. - - struct - { - BIGNUM *p; // prime number (shared) - BIGNUM *g; // generator of Z_p (shared) - BIGNUM *priv_key; // private DH value x - BIGNUM *pub_key; // public DH value g^x - // ... - }; - DH - -Note that DH keys may use non-standard B<DH_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DH -structure elements directly and instead use API functions to query or -modify keys. - -=head1 SEE ALSO - -L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>, -L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>, -L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, -L<DH_generate_parameters(3)|DH_generate_parameters(3)>, -L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/dsa.pod b/openssl/trunk/doc/crypto/dsa.pod deleted file mode 100644 index da07d2b9..00000000 --- a/openssl/trunk/doc/crypto/dsa.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -dsa - Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/engine.h> - - DSA * DSA_new(void); - void DSA_free(DSA *dsa); - - int DSA_size(const DSA *dsa); - - DSA * DSA_generate_parameters(int bits, unsigned char *seed, - int seed_len, int *counter_ret, unsigned long *h_ret, - void (*callback)(int, int, void *), void *cb_arg); - - DH * DSA_dup_DH(const DSA *r); - - int DSA_generate_key(DSA *dsa); - - int DSA_sign(int dummy, const unsigned char *dgst, int len, - unsigned char *sigret, unsigned int *siglen, DSA *dsa); - int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, - BIGNUM **rp); - int DSA_verify(int dummy, const unsigned char *dgst, int len, - const unsigned char *sigbuf, int siglen, DSA *dsa); - - void DSA_set_default_method(const DSA_METHOD *meth); - const DSA_METHOD *DSA_get_default_method(void); - int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); - DSA *DSA_new_method(ENGINE *engine); - const DSA_METHOD *DSA_OpenSSL(void); - - int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DSA_set_ex_data(DSA *d, int idx, char *arg); - char *DSA_get_ex_data(DSA *d, int idx); - - DSA_SIG *DSA_SIG_new(void); - void DSA_SIG_free(DSA_SIG *a); - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); - - DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); - int DSA_do_verify(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - - DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - int i2d_DSAparams(const DSA *a,unsigned char **pp); - - int DSAparams_print(BIO *bp, const DSA *x); - int DSAparams_print_fp(FILE *fp, const DSA *x); - int DSA_print(BIO *bp, const DSA *x, int off); - int DSA_print_fp(FILE *bp, const DSA *x, int off); - -=head1 DESCRIPTION - -These functions implement the Digital Signature Algorithm (DSA). The -generation of shared DSA parameters is described in -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>; -L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to -generate a signature key. Signature generation and verification are -described in L<DSA_sign(3)|DSA_sign(3)>. - -The B<DSA> structure consists of several BIGNUM components. - - struct - { - BIGNUM *p; // prime number (public) - BIGNUM *q; // 160-bit subprime, q | p-1 (public) - BIGNUM *g; // generator of subgroup (public) - BIGNUM *priv_key; // private key x - BIGNUM *pub_key; // public key y = g^x - // ... - } - DSA; - -In public keys, B<priv_key> is NULL. - -Note that DSA keys may use non-standard B<DSA_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, -L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>, -L<DSA_new(3)|DSA_new(3)>, -L<DSA_size(3)|DSA_size(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, -L<DSA_dup_DH(3)|DSA_dup_DH(3)>, -L<DSA_generate_key(3)|DSA_generate_key(3)>, -L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, -L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/ecdsa.pod b/openssl/trunk/doc/crypto/ecdsa.pod deleted file mode 100644 index 49b10f22..00000000 --- a/openssl/trunk/doc/crypto/ecdsa.pod +++ /dev/null @@ -1,210 +0,0 @@ -=pod - -=head1 NAME - -ecdsa - Elliptic Curve Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/ecdsa.h> - - ECDSA_SIG* ECDSA_SIG_new(void); - void ECDSA_SIG_free(ECDSA_SIG *sig); - int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); - ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, - long len); - - ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, - EC_KEY *eckey); - ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, - const BIGNUM *kinv, const BIGNUM *rp, - EC_KEY *eckey); - int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, - const ECDSA_SIG *sig, EC_KEY* eckey); - int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, - BIGNUM **kinv, BIGNUM **rp); - int ECDSA_sign(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, EC_KEY *eckey); - int ECDSA_sign_ex(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, const BIGNUM *kinv, - const BIGNUM *rp, EC_KEY *eckey); - int ECDSA_verify(int type, const unsigned char *dgst, - int dgstlen, const unsigned char *sig, - int siglen, EC_KEY *eckey); - int ECDSA_size(const EC_KEY *eckey); - - const ECDSA_METHOD* ECDSA_OpenSSL(void); - void ECDSA_set_default_method(const ECDSA_METHOD *meth); - const ECDSA_METHOD* ECDSA_get_default_method(void); - int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); - - int ECDSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); - void* ECDSA_get_ex_data(EC_KEY *d, int idx); - -=head1 DESCRIPTION - -The B<ECDSA_SIG> structure consists of two BIGNUMs for the -r and s value of a ECDSA signature (see X9.62 or FIPS 186-2). - - struct - { - BIGNUM *r; - BIGNUM *s; - } ECDSA_SIG; - -ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this -function also allocates the BIGNUMs) and initialize it. - -ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. - -i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature -B<sig> and writes the encoded signature to B<*pp> (note: if B<pp> -is NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of -the DER encoded signature). B<i2d_ECDSA_SIG> returns the length -of the DER encoded signature (or 0 on error). - -d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns -the decoded signature in a newly allocated B<ECDSA_SIG> structure. -B<*sig> points to the buffer containing the DER encoded signature -of size B<len>. - -ECDSA_size() returns the maximum length of a DER encoded -ECDSA signature created with the private EC key B<eckey>. - -ECDSA_sign_setup() may be used to precompute parts of the -signing operation. B<eckey> is the private EC key and B<ctx> -is a pointer to B<BN_CTX> structure (or NULL). The precomputed -values or returned in B<kinv> and B<rp> and can be used in a -later call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>. - -ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv> -and B<rp> set to NULL. - -ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes -hash value B<dgst> using the private EC key B<eckey> and the optional -pre-computed values B<kinv> and B<rp>. The DER encoded signatures is -stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> -must point to B<ECDSA_size> bytes of memory. The parameter B<type> -is ignored. - -ECDSA_verify() verifies that the signature in B<sig> of size -B<siglen> is a valid ECDSA signature of the hash value -value B<dgst> of size B<dgstlen> using the public key B<eckey>. -The parameter B<type> is ignored. - -ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv> -and B<rp> set to NULL. - -ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len> -bytes hash value B<dgst> using the private key B<eckey> and the -optional pre-computed values B<kinv> and B<rp>. The signature is -returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error). - -ECDSA_do_verify() verifies that the signature B<sig> is a valid -ECDSA signature of the hash value B<dgst> of size B<dgst_len> -using the public key B<eckey>. - -=head1 RETURN VALUES - -ECDSA_size() returns the maximum length signature or 0 on error. - -ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or -1 -on error. - -ECDSA_verify() and ECDSA_do_verify() return 1 for a valid -signature, 0 for an invalid signature and -1 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 EXAMPLES - -Creating a ECDSA signature of given SHA-1 hash value using the -named curve secp192k1. - -First step: create a EC_KEY object (note: this part is B<not> ECDSA -specific) - - int ret; - ECDSA_SIG *sig; - EC_KEY *eckey = EC_KEY_new(); - if (eckey == NULL) - { - /* error */ - } - key->group = EC_GROUP_new_by_nid(NID_secp192k1); - if (key->group == NULL) - { - /* error */ - } - if (!EC_KEY_generate_key(eckey)) - { - /* error */ - } - -Second step: compute the ECDSA signature of a SHA-1 hash value -using B<ECDSA_do_sign> - - sig = ECDSA_do_sign(digest, 20, eckey); - if (sig == NULL) - { - /* error */ - } - -or using B<ECDSA_sign> - - unsigned char *buffer, *pp; - int buf_len; - buf_len = ECDSA_size(eckey); - buffer = OPENSSL_malloc(buf_len); - pp = buffer; - if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey); - { - /* error */ - } - -Third step: verify the created ECDSA signature using B<ECDSA_do_verify> - - ret = ECDSA_do_verify(digest, 20, sig, eckey); - -or using B<ECDSA_verify> - - ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); - -and finally evaluate the return value: - - if (ret == -1) - { - /* error */ - } - else if (ret == 0) - { - /* incorrect signature */ - } - else /* ret == 1 */ - { - /* signature ok */ - } - -=head1 CONFORMING TO - -ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 -(Digital Signature Standard, DSS) - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)> - -=head1 HISTORY - -The ecdsa implementation was first introduced in OpenSSL 0.9.8 - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/openssl/trunk/doc/crypto/engine.pod b/openssl/trunk/doc/crypto/engine.pod deleted file mode 100644 index 75933fcc..00000000 --- a/openssl/trunk/doc/crypto/engine.pod +++ /dev/null @@ -1,599 +0,0 @@ -=pod - -=head1 NAME - -engine - 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_openssl(void); - void ENGINE_load_dynamic(void); - #ifndef OPENSSL_NO_STATIC_ENGINE - void ENGINE_load_4758cca(void); - void ENGINE_load_aep(void); - void ENGINE_load_atalla(void); - void ENGINE_load_chil(void); - void ENGINE_load_cswift(void); - void ENGINE_load_gmp(void); - void ENGINE_load_nuron(void); - void ENGINE_load_sureware(void); - void ENGINE_load_ubsec(void); - #endif - void ENGINE_load_cryptodev(void); - void ENGINE_load_builtin_engines(void); - - void ENGINE_cleanup(void); - - ENGINE *ENGINE_get_default_RSA(void); - ENGINE *ENGINE_get_default_DSA(void); - ENGINE *ENGINE_get_default_ECDH(void); - 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_STORE(ENGINE *e); - void ENGINE_unregister_STORE(ENGINE *e); - void ENGINE_register_all_STORE(void); - int ENGINE_register_ciphers(ENGINE *e); - void ENGINE_unregister_ciphers(ENGINE *e); - void ENGINE_register_all_ciphers(void); - 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); - - int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); - void *ENGINE_get_ex_data(const ENGINE *e, int idx); - - int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); - - ENGINE *ENGINE_new(void); - int ENGINE_free(ENGINE *e); - int ENGINE_up_ref(ENGINE *e); - - 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_STORE(ENGINE *e, const STORE_METHOD *rand_meth); - int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); - int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); - int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); - 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); - const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); - ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); - ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); - ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); - 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); - - void ENGINE_add_conf_module(void); - -=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, - STORE_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) independantly. - -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 -initiliased 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 independantly. If you have a functional reference to an -ENGINE, you have a guarantee that the ENGINE has been initialised ready to -perform cryptographic operations and will remain uninitialised -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, eg. - - /* Make the "dynamic" ENGINE available */ - void ENGINE_load_dynamic(void); - /* Make the CryptoSwift hardware acceleration support available */ - void ENGINE_load_cswift(void); - /* Make support for nCipher's "CHIL" hardware available */ - void ENGINE_load_chil(void); - ... - /* Make ALL ENGINE implementations bundled with OpenSSL available */ - void ENGINE_load_builtin_engines(void); - -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 if any ENGINEs are loaded, even if they are never registered or -used, it is necessary to use the ENGINE_cleanup() function to -correspondingly cleanup before program exit, if the caller wishes to avoid -memory leaks. This mechanism uses an internal callback registration table -so that any ENGINE API functionality that knows it requires cleanup can -register its cleanup details to be called during ENGINE_cleanup(). This -approach allows ENGINE_cleanup() to clean up after any ENGINE functionality -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. - -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 operation, 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 initialise, -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 the control -commands implemented by a given ENGINE, specifically the commands; - - #define ENGINE_HAS_CTRL_FUNCTION 10 - #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 - #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 - #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 - #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 - #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 - #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 - #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 - #define ENGINE_CTRL_GET_CMD_FLAGS 18 - -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; - - #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 - #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 - #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 - #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 - -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 determinie if an ENGINE -supports certain specific commands it might want to use (eg. application "foo" -might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - -and ENGINE could therefore decide whether or not to support this "foo"-specific -extension). - -=head2 Future developments - -The ENGINE API and internal architecture is currently being reviewed. Slated for -possible release in 0.9.8 is support for transparent loading of "dynamic" -ENGINEs (built as self-contained shared-libraries). This would allow ENGINE -implementations to be provided independantly of OpenSSL libraries and/or -OpenSSL-based applications, and would also remove any requirement for -applications to explicitly use the "dynamic" ENGINE to bind to shared-library -implementations. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/err.pod b/openssl/trunk/doc/crypto/err.pod deleted file mode 100644 index 6f729554..00000000 --- a/openssl/trunk/doc/crypto/err.pod +++ /dev/null @@ -1,187 +0,0 @@ -=pod - -=head1 NAME - -err - error codes - -=head1 SYNOPSIS - - #include <openssl/err.h> - - unsigned long ERR_get_error(void); - unsigned long ERR_peek_error(void); - unsigned long ERR_get_error_line(const char **file, int *line); - unsigned long ERR_peek_error_line(const char **file, int *line); - unsigned long ERR_get_error_line_data(const char **file, int *line, - const char **data, int *flags); - unsigned long ERR_peek_error_line_data(const char **file, int *line, - const char **data, int *flags); - - int ERR_GET_LIB(unsigned long e); - int ERR_GET_FUNC(unsigned long e); - int ERR_GET_REASON(unsigned long e); - - void ERR_clear_error(void); - - char *ERR_error_string(unsigned long e, char *buf); - const char *ERR_lib_error_string(unsigned long e); - const char *ERR_func_error_string(unsigned long e); - const char *ERR_reason_error_string(unsigned long e); - - void ERR_print_errors(BIO *bp); - void ERR_print_errors_fp(FILE *fp); - - void ERR_load_crypto_strings(void); - void ERR_free_strings(void); - - void ERR_remove_state(unsigned long pid); - - void ERR_put_error(int lib, int func, int reason, const char *file, - int line); - void ERR_add_error_data(int num, ...); - - void ERR_load_strings(int lib,ERR_STRING_DATA str[]); - unsigned long ERR_PACK(int lib, int func, int reason); - int ERR_get_next_error_library(void); - -=head1 DESCRIPTION - -When a call to the OpenSSL library fails, this is usually signalled -by the return value, and an error code is stored in an error queue -associated with the current thread. The B<err> library provides -functions to obtain these error codes and textual error messages. - -The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to -access error codes. - -Error codes contain information about where the error occurred, and -what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to -extract this information. A method to obtain human-readable error -messages is described in L<ERR_error_string(3)|ERR_error_string(3)>. - -L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the -error queue. - -Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to -avoid memory leaks when threads are terminated. - -=head1 ADDING NEW ERROR CODES TO OPENSSL - -See L<ERR_put_error(3)> if you want to record error codes in the -OpenSSL error system from within your application. - -The remainder of this section is of interest only if you want to add -new error codes to OpenSSL or add error codes from external libraries. - -=head2 Reporting errors - -Each sub-library has a specific macro XXXerr() that is used to report -errors. Its first argument is a function code B<XXX_F_...>, the second -argument is a reason code B<XXX_R_...>. Function codes are derived -from the function names; reason codes consist of textual error -descriptions. For example, the function ssl23_read() reports a -"handshake failure" as follows: - - SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); - -Function and reason codes should consist of upper case characters, -numbers and underscores only. The error file generation script translates -function codes into function names by looking in the header files -for an appropriate function name, if none is found it just uses -the capitalized form such as "SSL23_READ" in the above example. - -The trailing section of a reason code (after the "_R_") is translated -into lower case and underscores changed to spaces. - -When you are using new function or reason codes, run B<make errors>. -The necessary B<#define>s will then automatically be added to the -sub-library's header file. - -Although a library will normally report errors using its own specific -XXXerr macro, another library's macro can be used. This is normally -only done when a library wants to include ASN1 code which must use -the ASN1err() macro. - -=head2 Adding new libraries - -When adding a new sub-library to OpenSSL, assign it a library number -B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its -name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add -C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function -(in B<crypto/err/err_all.c>). Finally, add an entry - - L XXX xxx.h xxx_err.c - -to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile. -Running B<make errors> will then generate a file B<xxx_err.c>, and -add all error codes used in the library to B<xxx.h>. - -Additionally the library include file must have a certain form. -Typically it will initially look like this: - - #ifndef HEADER_XXX_H - #define HEADER_XXX_H - - #ifdef __cplusplus - extern "C" { - #endif - - /* Include files */ - - #include <openssl/bio.h> - #include <openssl/x509.h> - - /* Macros, structures and function prototypes */ - - - /* BEGIN ERROR CODES */ - -The B<BEGIN ERROR CODES> sequence is used by the error code -generation script as the point to place new error codes, any text -after this point will be overwritten when B<make errors> is run. -The closing #endif etc will be automatically added by the script. - -The generated C error code file B<xxx_err.c> will load the header -files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the -header file must load any additional header files containing any -definitions it uses. - -=head1 USING ERROR CODES IN EXTERNAL LIBRARIES - -It is also possible to use OpenSSL's error code scheme in external -libraries. The library needs to load its own codes and call the OpenSSL -error code insertion script B<mkerr.pl> explicitly to add codes to -the header file and generate the C error code file. This will normally -be done if the external library needs to generate new ASN1 structures -but it can also be used to add more general purpose error code handling. - -TBA more details - -=head1 INTERNALS - -The error queues are stored in a hash table with one B<ERR_STATE> -entry for each pid. ERR_get_state() returns the current thread's -B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error -codes. When more error codes are added, the old ones are overwritten, -on the assumption that the most recent errors are most important. - -Error strings are also stored in hash table. The hash tables can -be obtained by calling ERR_get_err_state_table(void) and -ERR_get_string_table(void) respectively. - -=head1 SEE ALSO - -L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>, -L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>, -L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>, -L<ERR_clear_error(3)|ERR_clear_error(3)>, -L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_print_errors(3)|ERR_print_errors(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<ERR_remove_state(3)|ERR_remove_state(3)>, -L<ERR_put_error(3)|ERR_put_error(3)>, -L<ERR_load_strings(3)|ERR_load_strings(3)>, -L<SSL_get_error(3)|SSL_get_error(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/evp.pod b/openssl/trunk/doc/crypto/evp.pod deleted file mode 100644 index b3ca1431..00000000 --- a/openssl/trunk/doc/crypto/evp.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=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. - -B<EVP_Seal>I<...> and B<EVP_Open>I<...> provide public key encryption -and decryption to implement digital "envelopes". - -The B<EVP_Sign>I<...> and B<EVP_Verify>I<...> functions implement -digital signatures. - -Symmetric encryption is available with the B<EVP_Encrypt>I<...> -functions. The B<EVP_Digest>I<...> functions provide message digests. - -Algorithms are loaded with OpenSSL_add_all_algorithms(3). - -All the symmetric algorithms (ciphers) and digests can be replaced by ENGINE -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. - -=head1 SEE ALSO - -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_OpenInit(3)|EVP_OpenInit(3)>, -L<EVP_SealInit(3)|EVP_SealInit(3)>, -L<EVP_SignInit(3)|EVP_SignInit(3)>, -L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, -L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>, -L<engine(3)|engine(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/hmac.pod b/openssl/trunk/doc/crypto/hmac.pod deleted file mode 100644 index 0bd79a6d..00000000 --- a/openssl/trunk/doc/crypto/hmac.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - 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); - - void HMAC_CTX_init(HMAC_CTX *ctx); - - void HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md); - void HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md, ENGINE *impl); - void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); - void HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); - - void HMAC_CTX_cleanup(HMAC_CTX *ctx); - void HMAC_cleanup(HMAC_CTX *ctx); - -=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. -B<key> and B<evp_md> may be B<NULL> if a key and hash function have -been set in a previous call to HMAC_Init() for that B<HMAC_CTX>. - -HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be -called. - -HMAC_CTX_cleanup() erases the key and other data from the B<HMAC_CTX> -and releases any associated resources. It must be called when an -B<HMAC_CTX> is no longer required. - -HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back -compatibility with 0.9.6b, it is deprecated. - -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 function B<evp_md> and key B<key>. Either can be NULL, in which -case the existing one will be reused. HMAC_CTX_init() must have been -called 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>. - -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. - -=head1 RETURN VALUES - -HMAC() returns a pointer to the message authentication code. - -HMAC_CTX_init(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and -HMAC_CTX_cleanup() do not return values. - -=head1 CONFORMING TO - -RFC 2104 - -=head1 SEE ALSO - -L<sha(3)|sha(3)>, L<evp(3)|evp(3)> - -=head1 HISTORY - -HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() -are available since SSLeay 0.9.0. - -HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available -since OpenSSL 0.9.7. - -=cut diff --git a/openssl/trunk/doc/crypto/lh_stats.pod b/openssl/trunk/doc/crypto/lh_stats.pod deleted file mode 100644 index 3eeaa72e..00000000 --- a/openssl/trunk/doc/crypto/lh_stats.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, -lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics - -=head1 SYNOPSIS - - #include <openssl/lhash.h> - - void lh_stats(LHASH *table, FILE *out); - void lh_node_stats(LHASH *table, FILE *out); - void lh_node_usage_stats(LHASH *table, FILE *out); - - void lh_stats_bio(LHASH *table, BIO *out); - void lh_node_stats_bio(LHASH *table, BIO *out); - void lh_node_usage_stats_bio(LHASH *table, BIO *out); - -=head1 DESCRIPTION - -The B<LHASH> structure records statistics about most aspects of -accessing the hash table. This is mostly a legacy of Eric Young -writing this library for the reasons of implementing what looked like -a nice algorithm rather than for a particular software product. - -lh_stats() prints out statistics on the size of the hash table, how -many entries are in it, and the number and result of calls to the -routines in this library. - -lh_node_stats() prints the number of entries for each 'bucket' in the -hash table. - -lh_node_usage_stats() prints out a short summary of the state of the -hash table. It prints the 'load' and the 'actual load'. The load is -the average number of data items per 'bucket' in the hash table. The -'actual load' is the average number of items per 'bucket', but only -for buckets which contain entries. So the 'actual load' is the -average number of searches that will need to find an item in the hash -table, while the 'load' is the average number that will be done to -record a miss. - -lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio() -are the same as the above, except that the output goes to a B<BIO>. - -=head1 RETURN VALUES - -These functions do not return values. - -=head1 SEE ALSO - -L<bio(3)|bio(3)>, L<lhash(3)|lhash(3)> - -=head1 HISTORY - -These functions are available in all versions of SSLeay and OpenSSL. - -This manpage is derived from the SSLeay documentation. - -=cut diff --git a/openssl/trunk/doc/crypto/lhash.pod b/openssl/trunk/doc/crypto/lhash.pod deleted file mode 100644 index dcdbb43a..00000000 --- a/openssl/trunk/doc/crypto/lhash.pod +++ /dev/null @@ -1,294 +0,0 @@ -=pod - -=head1 NAME - -lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error - dynamic hash table - -=head1 SYNOPSIS - - #include <openssl/lhash.h> - - LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare); - void lh_free(LHASH *table); - - void *lh_insert(LHASH *table, void *data); - void *lh_delete(LHASH *table, void *data); - void *lh_retrieve(LHASH *table, void *data); - - void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func); - void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func, - void *arg); - - int lh_error(LHASH *table); - - typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); - typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); - -=head1 DESCRIPTION - -This library implements dynamic hash tables. The hash table entries -can be arbitrary structures. Usually they consist of key and value -fields. - -lh_new() creates a new B<LHASH> structure to store arbitrary data -entries, and provides the 'hash' and 'compare' callbacks to be used in -organising the table's entries. The B<hash> callback takes a pointer -to a table entry as its argument and returns an unsigned long hash -value for its key field. The hash value is normally truncated to a -power of 2, so make sure that your hash function returns well mixed -low order bits. The B<compare> callback takes two arguments (pointers -to two hash table entries), and returns 0 if their keys are equal, -non-zero otherwise. If your hash table will contain items of some -particular type and the B<hash> and B<compare> callbacks hash/compare -these types, then the B<DECLARE_LHASH_HASH_FN> and -B<IMPLEMENT_LHASH_COMP_FN> macros can be used to create callback -wrappers of the prototypes required by lh_new(). These provide -per-variable casts before calling the type-specific callbacks written -by the application author. These macros, as well as those used for -the "doall" callbacks, are defined as; - - #define DECLARE_LHASH_HASH_FN(f_name,o_type) \ - unsigned long f_name##_LHASH_HASH(const void *); - #define IMPLEMENT_LHASH_HASH_FN(f_name,o_type) \ - unsigned long f_name##_LHASH_HASH(const void *arg) { \ - o_type a = (o_type)arg; \ - return f_name(a); } - #define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH - - #define DECLARE_LHASH_COMP_FN(f_name,o_type) \ - int f_name##_LHASH_COMP(const void *, const void *); - #define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \ - int f_name##_LHASH_COMP(const void *arg1, const void *arg2) { \ - o_type a = (o_type)arg1; \ - o_type b = (o_type)arg2; \ - return f_name(a,b); } - #define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP - - #define DECLARE_LHASH_DOALL_FN(f_name,o_type) \ - void f_name##_LHASH_DOALL(const void *); - #define IMPLEMENT_LHASH_DOALL_FN(f_name,o_type) \ - void f_name##_LHASH_DOALL(const void *arg) { \ - o_type a = (o_type)arg; \ - f_name(a); } - #define LHASH_DOALL_FN(f_name) f_name##_LHASH_DOALL - - #define DECLARE_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \ - void f_name##_LHASH_DOALL_ARG(const void *, const void *); - #define IMPLEMENT_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \ - void f_name##_LHASH_DOALL_ARG(const void *arg1, const void *arg2) { \ - o_type a = (o_type)arg1; \ - a_type b = (a_type)arg2; \ - f_name(a,b); } - #define LHASH_DOALL_ARG_FN(f_name) f_name##_LHASH_DOALL_ARG - -An example of a hash table storing (pointers to) structures of type 'STUFF' -could be defined as follows; - - /* Calculates the hash value of 'tohash' (implemented elsewhere) */ - unsigned long STUFF_hash(const STUFF *tohash); - /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ - int STUFF_cmp(const STUFF *arg1, const STUFF *arg2); - /* Create the type-safe wrapper functions for use in the LHASH internals */ - static IMPLEMENT_LHASH_HASH_FN(STUFF_hash, const STUFF *) - static IMPLEMENT_LHASH_COMP_FN(STUFF_cmp, const STUFF *); - /* ... */ - int main(int argc, char *argv[]) { - /* Create the new hash table using the hash/compare wrappers */ - LHASH *hashtable = lh_new(LHASH_HASH_FN(STUFF_hash), - LHASH_COMP_FN(STUFF_cmp)); - /* ... */ - } - -lh_free() frees the B<LHASH> structure B<table>. Allocated hash table -entries will not be freed; consider using lh_doall() to deallocate any -remaining entries in the hash table (see below). - -lh_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_insert() stores pointers, the data are not -copied. - -lh_delete() deletes an entry from B<table>. - -lh_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_doall() will, for every entry in the hash table, call B<func> with -the data item as its parameter. For lh_doall() and lh_doall_arg(), -function pointer casting should be avoided in the callbacks (see -B<NOTE>) - instead, either declare the callbacks to match the -prototype required in lh_new() or use the declare/implement macros to -create type-safe wrappers that cast variables prior to calling your -type-specific callbacks. An example of this is illustrated here where -the callback is used to cleanup resources for items in the hash table -prior to the hashtable itself being deallocated: - - /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ - void STUFF_cleanup(STUFF *a); - /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ - IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF *) - /* ... then later in the code ... */ - /* So to run "STUFF_cleanup" against all items in a hash table ... */ - lh_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); - /* Then the hash table itself can be deallocated */ - lh_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_doall_arg() is the same as lh_doall() except that B<func> will be -called with B<arg> as the second argument and B<func> should be of -type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype that is passed -both the table entry and an extra argument). As with lh_doall(), you -can instead choose to declare your callback with a prototype matching -the types you are dealing with and use the declare/implement macros to -create compatible wrappers that cast variables before calling your -type-specific callbacks. An example of this is demonstrated here -(printing all hash table entries to a BIO that is provided by the -caller): - - /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ - void STUFF_print(const STUFF *a, BIO *output_bio); - /* Implement a prototype-compatible wrapper for "STUFF_print" */ - static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF_print, const STUFF *, BIO *) - /* ... then later in the code ... */ - /* Print out the entire hashtable to a particular BIO */ - lh_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), logging_bio); - -lh_error() can be used to determine if an error occurred in the last -operation. lh_error() is a macro. - -=head1 RETURN VALUES - -lh_new() returns B<NULL> on error, otherwise a pointer to the new -B<LHASH> structure. - -When a hash table entry is replaced, lh_insert() returns the value -being replaced. B<NULL> is returned on normal operation and on error. - -lh_delete() returns the entry being deleted. B<NULL> is returned if -there is no such value in the hash table. - -lh_retrieve() returns the hash table entry if it has been found, -B<NULL> otherwise. - -lh_error() returns 1 if an error occurred in the last operation, 0 -otherwise. - -lh_free(), lh_doall() and lh_doall_arg() return no values. - -=head1 NOTE - -The various LHASH macros and callback types exist to make it possible -to write type-safe code without resorting to function-prototype -casting - an evil that makes application code much harder to -audit/verify and also opens the window of opportunity for stack -corruption and other hard-to-find bugs. It also, apparently, violates -ANSI-C. - -The LHASH code regards table entries as constant data. As such, it -internally represents lh_insert()'d items with a "const void *" -pointer type. This is why callbacks such as those used by lh_doall() -and lh_doall_arg() declare their prototypes with "const", even for the -parameters that pass back the table items' data pointers - for -consistency, user-provided data is "const" at all times as far as the -LHASH code is concerned. However, as callers are themselves providing -these pointers, they can choose whether they too should be treating -all such parameters as constant. - -As an example, a hash table may be maintained by code that, for -reasons of encapsulation, has only "const" access to the data being -indexed in the hash table (ie. it is returned as "const" from -elsewhere in their code) - in this case the LHASH prototypes are -appropriate as-is. Conversely, if the caller is responsible for the -life-time of the data in question, then they may well wish to make -modifications to table item passed back in the lh_doall() or -lh_doall_arg() callbacks (see the "STUFF_cleanup" example above). If -so, the caller can either cast the "const" away (if they're providing -the raw callbacks themselves) or use the macros to declare/implement -the wrapper functions without "const" types. - -Callers that only have "const" access to data they're indexing in a -table, yet declare callbacks without constant types (or cast the -"const" away themselves), are therefore creating their own risks/bugs -without being encouraged to do so by the API. On a related note, -those auditing code should pay special attention to any instances of -DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types -without any "const" qualifiers. - -=head1 BUGS - -lh_insert() returns B<NULL> both for success and error. - -=head1 INTERNALS - -The following description is based on the SSLeay documentation: - -The B<lhash> library implements a hash table described in the -I<Communications of the ACM> in 1991. What makes this hash table -different is that as the table fills, the hash table is increased (or -decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of -all hashes being redistributed over twice as many 'buckets', one -bucket is split. So when an 'expand' is done, there is only a minimal -cost to redistribute some values. Subsequent inserts will cause more -single 'bucket' redistributions but there will never be a sudden large -cost due to redistributing all the 'buckets'. - -The state for a particular hash table is kept in the B<LHASH> structure. -The decision to increase or decrease the hash table size is made -depending on the 'load' of the hash table. The load is the number of -items in the hash table divided by the size of the hash table. The -default values are as follows. If (hash->up_load E<lt> load) =E<gt> -expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The -B<up_load> has a default value of 1 and B<down_load> has a default value -of 2. These numbers can be modified by the application by just -playing with the B<up_load> and B<down_load> variables. The 'load' is -kept in a form which is multiplied by 256. So -hash-E<gt>up_load=8*256; will cause a load of 8 to be set. - -If you are interested in performance the field to watch is -num_comp_calls. The hash library keeps track of the 'hash' value for -each item so when a lookup is done, the 'hashes' are compared, if -there is a match, then a full compare is done, and -hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal -to num_delete plus num_retrieve it means that your hash function is -generating hashes that are the same for different values. It is -probably worth changing your hash function if this is the case because -even if your hash table has 10 items in a 'bucket', it can be searched -with 10 B<unsigned long> compares and 10 linked list traverses. This -will be much less expensive that 10 calls to your compare function. - -lh_strhash() is a demo string hashing function: - - unsigned long lh_strhash(const char *c); - -Since the B<LHASH> routines would normally be passed structures, this -routine would not normally be passed to lh_new(), rather it would be -used in the function passed to lh_new(). - -=head1 SEE ALSO - -L<lh_stats(3)|lh_stats(3)> - -=head1 HISTORY - -The B<lhash> library is available in all versions of SSLeay and OpenSSL. -lh_error() was added in SSLeay 0.9.1b. - -This manpage is derived from the SSLeay documentation. - -In OpenSSL 0.9.7, all lhash functions that were passed function pointers -were changed for better type safety, and the function types LHASH_COMP_FN_TYPE, -LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE -became available. - -=cut diff --git a/openssl/trunk/doc/crypto/md5.pod b/openssl/trunk/doc/crypto/md5.pod deleted file mode 100644 index 6e6322dc..00000000 --- a/openssl/trunk/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); - - void MD2_Init(MD2_CTX *c); - void MD2_Update(MD2_CTX *c, const unsigned char *data, - unsigned long len); - void 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); - - void MD4_Init(MD4_CTX *c); - void MD4_Update(MD4_CTX *c, const void *data, - unsigned long len); - void 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); - - void MD5_Init(MD5_CTX *c); - void MD5_Update(MD5_CTX *c, const void *data, - unsigned long len); - void 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)|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() do not return -values. - -=head1 CONFORMING TO - -RFC 1319, RFC 1320, RFC 1321 - -=head1 SEE ALSO - -L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), -MD5_Update() and MD5_Final() are available in all versions of SSLeay -and OpenSSL. - -MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and -above. - -=cut diff --git a/openssl/trunk/doc/crypto/mdc2.pod b/openssl/trunk/doc/crypto/mdc2.pod deleted file mode 100644 index 11dc303e..00000000 --- a/openssl/trunk/doc/crypto/mdc2.pod +++ /dev/null @@ -1,64 +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); - - void MDC2_Init(MDC2_CTX *c); - void MDC2_Update(MDC2_CTX *c, const unsigned char *data, - unsigned long len); - void 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)|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() do not return values. - -=head1 CONFORMING TO - -ISO/IEC 10118-2, with DES - -=head1 SEE ALSO - -L<sha(3)|sha(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since -SSLeay 0.8. - -=cut diff --git a/openssl/trunk/doc/crypto/pem.pod b/openssl/trunk/doc/crypto/pem.pod deleted file mode 100644 index 4f9a27df..00000000 --- a/openssl/trunk/doc/crypto/pem.pod +++ /dev/null @@ -1,476 +0,0 @@ -=pod - -=head1 NAME - -PEM - PEM routines - -=head1 SYNOPSIS - - #include <openssl/pem.h> - - EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - 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_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); - - NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); - - int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); - -=head1 DESCRIPTION - -The PEM functions read or write structures in PEM format. In -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 -"traditional" private key format and can handle both RSA and DSA -private keys. The read functions can additionally transparently -handle PKCS#8 format encrypted and unencrypted keys too. - -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 algoritm to -use: unlike all other PEM routines the encryption is applied at the -PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no -encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. - -PEM_write_bio_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. It 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. It 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 foobar structure. - -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. - -The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate -Sequence using a NETSCAPE_CERT_SEQUENCE structure. - -=head1 PEM FUNCTION ARGUMENTS - -The PEM functions have many common arguments. - -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 an unencrypted private key to a FILE pointer: - - if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) - { - /* 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 the pass phrase "hello": - - key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); - if (key == NULL) - { - /* 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", u); - - /* get pass phrase, length 'len' into 'tmp' */ - tmp = "hello"; - len = strlen(tmp); - - if (len <= 0) return 0; - /* if too long, truncate */ - 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 - -This 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 DEK-Info contains two comma separated pieces of information: -the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 -byte B<salt> encoded as a set of hexadecimal digits. - -After this is the base64 encoded encrypted data. - -The encryption key is determined using EVP_bytestokey(), using B<salt> and an -iteration count of 1. The IV used is the value of B<salt> and *not* the IV -returned by EVP_bytestokey(). - -=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. diff --git a/openssl/trunk/doc/crypto/rand.pod b/openssl/trunk/doc/crypto/rand.pod deleted file mode 100644 index 1c068c85..00000000 --- a/openssl/trunk/doc/crypto/rand.pod +++ /dev/null @@ -1,175 +0,0 @@ -=pod - -=head1 NAME - -rand - pseudo-random number generator - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - int RAND_set_rand_engine(ENGINE *engine); - - int RAND_bytes(unsigned char *buf, int num); - int RAND_pseudo_bytes(unsigned char *buf, int num); - - void RAND_seed(const void *buf, int num); - void RAND_add(const void *buf, int num, int entropy); - int RAND_status(void); - - int RAND_load_file(const char *file, long max_bytes); - int RAND_write_file(const char *file); - const char *RAND_file_name(char *file, size_t num); - - int RAND_egd(const char *path); - - void RAND_set_rand_method(const RAND_METHOD *meth); - const RAND_METHOD *RAND_get_rand_method(void); - RAND_METHOD *RAND_SSLeay(void); - - void RAND_cleanup(void); - - /* For Win32 only */ - void RAND_screen(void); - int RAND_event(UINT, WPARAM, LPARAM); - -=head1 DESCRIPTION - -Since the introduction of the ENGINE API, the recommended way of controlling -default implementations is by using the ENGINE API functions. The default -B<RAND_METHOD>, as set by RAND_set_rand_method() and returned by -RAND_get_rand_method(), is only used if no ENGINE has been set as the default -"rand" implementation. Hence, these two functions are no longer the recommened -way to control defaults. - -If an alternative B<RAND_METHOD> implementation is being used (either set -directly or as provided by an ENGINE module), then it is entirely responsible -for the generation and management of a cryptographically secure PRNG stream. The -mechanisms described below relate solely to the software PRNG implementation -built in to OpenSSL and used by default. - -These functions implement a cryptographically secure pseudo-random -number generator (PRNG). It is used by other library functions for -example to generate random keys, and applications can use it when they -need randomness. - -A cryptographic PRNG must be seeded with unpredictable data such as -mouse movements or keys pressed at random by the user. This is -described in L<RAND_add(3)|RAND_add(3)>. Its state can be saved in a seed file -(see L<RAND_load_file(3)|RAND_load_file(3)>) to avoid having to go through the -seeding process whenever the application is started. - -L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the -PRNG. - -=head1 INTERNALS - -The RAND_SSLeay() method implements a PRNG based on a cryptographic -hash function. - -The following description of its design is based on the SSLeay -documentation: - -First up I will state the things I believe I need for a good RNG. - -=over 4 - -=item 1 - -A good hashing algorithm to mix things up and to convert the RNG 'state' -to random numbers. - -=item 2 - -An initial source of random 'state'. - -=item 3 - -The state should be very large. If the RNG is being used to generate -4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). -If your RNG state only has 128 bits, you are obviously limiting the -search space to 128 bits, not 2048. I'm probably getting a little -carried away on this last point but it does indicate that it may not be -a bad idea to keep quite a lot of RNG state. It should be easier to -break a cipher than guess the RNG seed data. - -=item 4 - -Any RNG seed data should influence all subsequent random numbers -generated. This implies that any random seed data entered will have -an influence on all subsequent random numbers generated. - -=item 5 - -When using data to seed the RNG state, the data used should not be -extractable from the RNG state. I believe this should be a -requirement because one possible source of 'secret' semi random -data would be a private key or a password. This data must -not be disclosed by either subsequent random numbers or a -'core' dump left by a program crash. - -=item 6 - -Given the same initial 'state', 2 systems should deviate in their RNG state -(and hence the random numbers generated) over time if at all possible. - -=item 7 - -Given the random number output stream, it should not be possible to determine -the RNG state or the next random number. - -=back - -The algorithm is as follows. - -There is global state made up of a 1023 byte buffer (the 'state'), a -working hash value ('md'), and a counter ('count'). - -Whenever seed data is added, it is inserted into the 'state' as -follows. - -The input is chopped up into units of 20 bytes (or less for -the last block). Each of these blocks is run through the hash -function as follows: The data passed to the hash function -is the current 'md', the same number of bytes from the 'state' -(the location determined by in incremented looping index) as -the current 'block', the new key data 'block', and 'count' -(which is incremented after each use). -The result of this is kept in 'md' and also xored into the -'state' at the same locations that were used as input into the -hash function. I -believe this system addresses points 1 (hash function; currently -SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash -function and xor). - -When bytes are extracted from the RNG, the following process is used. -For each group of 10 bytes (or less), we do the following: - -Input into the hash function the local 'md' (which is initialized from -the global 'md' before any bytes are generated), the bytes that are to -be overwritten by the random bytes, and bytes from the 'state' -(incrementing looping index). From this digest output (which is kept -in 'md'), the top (up to) 10 bytes are returned to the caller and the -bottom 10 bytes are xored into the 'state'. - -Finally, after we have finished 'num' random bytes for the caller, -'count' (which is incremented) and the local and global 'md' are fed -into the hash function and the results are kept in the global 'md'. - -I believe the above addressed points 1 (use of SHA-1), 6 (by hashing -into the 'state' the 'old' data from the caller that is about to be -overwritten) and 7 (by not using the 10 bytes given to the caller to -update the 'state', but they are used to update 'md'). - -So of the points raised, only 2 is not addressed (but see -L<RAND_add(3)|RAND_add(3)>). - -=head1 SEE ALSO - -L<BN_rand(3)|BN_rand(3)>, L<RAND_add(3)|RAND_add(3)>, -L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_egd(3)|RAND_egd(3)>, -L<RAND_bytes(3)|RAND_bytes(3)>, -L<RAND_set_rand_method(3)|RAND_set_rand_method(3)>, -L<RAND_cleanup(3)|RAND_cleanup(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/rc4.pod b/openssl/trunk/doc/crypto/rc4.pod deleted file mode 100644 index b6d3a434..00000000 --- a/openssl/trunk/doc/crypto/rc4.pod +++ /dev/null @@ -1,62 +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. - -Applications should use the higher level functions -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> -etc. instead of calling the RC4 functions directly. - -=head1 RETURN VALUES - -RC4_set_key() and RC4() do not return values. - -=head1 NOTE - -Certain conditions have to be observed to securely use stream ciphers. -It is not permissible to perform multiple encryptions using the same -key stream. - -=head1 SEE ALSO - -L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> - -=head1 HISTORY - -RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/ripemd.pod b/openssl/trunk/doc/crypto/ripemd.pod deleted file mode 100644 index 31054b6a..00000000 --- a/openssl/trunk/doc/crypto/ripemd.pod +++ /dev/null @@ -1,66 +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); - - void RIPEMD160_Init(RIPEMD160_CTX *c); - void RIPEMD160_Update(RIPEMD_CTX *c, const void *data, - unsigned long len); - void 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>. - -Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the -hash functions directly. - -=head1 RETURN VALUES - -RIPEMD160() returns a pointer to the hash value. - -RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() do not -return values. - -=head1 CONFORMING TO - -ISO/IEC 10118-3 (draft) (??) - -=head1 SEE ALSO - -L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and -RIPEMD160_Final() are available since SSLeay 0.9.0. - -=cut diff --git a/openssl/trunk/doc/crypto/rsa.pod b/openssl/trunk/doc/crypto/rsa.pod deleted file mode 100644 index 45ac53ff..00000000 --- a/openssl/trunk/doc/crypto/rsa.pod +++ /dev/null @@ -1,123 +0,0 @@ -=pod - -=head1 NAME - -rsa - RSA public key cryptosystem - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - #include <openssl/engine.h> - - RSA * RSA_new(void); - void RSA_free(RSA *rsa); - - int RSA_public_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - int RSA_public_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - - int RSA_sign(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - int RSA_verify(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - - int RSA_size(const RSA *rsa); - - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - - int RSA_check_key(RSA *rsa); - - int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); - void RSA_blinding_off(RSA *rsa); - - void RSA_set_default_method(const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_default_method(void); - int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_method(const RSA *rsa); - RSA_METHOD *RSA_PKCS1_SSLeay(void); - RSA_METHOD *RSA_null_method(void); - int RSA_flags(const RSA *rsa); - RSA *RSA_new_method(ENGINE *engine); - - int RSA_print(BIO *bp, RSA *x, int offset); - int RSA_print_fp(FILE *fp, RSA *x, int offset); - - int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int RSA_set_ex_data(RSA *r,int idx,char *arg); - char *RSA_get_ex_data(RSA *r, int idx); - - int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigret, unsigned int *siglen, - RSA *rsa); - int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, - RSA *rsa); - -=head1 DESCRIPTION - -These functions implement RSA public key encryption and signatures -as defined in PKCS #1 v2.0 [RFC 2437]. - -The B<RSA> structure consists of several BIGNUM components. It can -contain public as well as private RSA keys: - - struct - { - BIGNUM *n; // public modulus - BIGNUM *e; // public exponent - BIGNUM *d; // private exponent - BIGNUM *p; // secret prime factor - BIGNUM *q; // secret prime factor - BIGNUM *dmp1; // d mod (p-1) - BIGNUM *dmq1; // d mod (q-1) - BIGNUM *iqmp; // q^-1 mod p - // ... - }; - RSA - -In public keys, the private exponent and the related secret values are -B<NULL>. - -B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private -keys, but the RSA operations are much faster when these values are -available. - -Note that RSA keys may use non-standard B<RSA_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using RSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 PATENTS - -RSA was covered by a US patent which expired in September 2000. - -=head1 SEE ALSO - -L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, -L<rand(3)|rand(3)>, L<engine(3)|engine(3)>, L<RSA_new(3)|RSA_new(3)>, -L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>, -L<RSA_generate_key(3)|RSA_generate_key(3)>, -L<RSA_check_key(3)|RSA_check_key(3)>, -L<RSA_blinding_on(3)|RSA_blinding_on(3)>, -L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>, -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, -L<RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3)>, -L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/sha.pod b/openssl/trunk/doc/crypto/sha.pod deleted file mode 100644 index 0ba315d6..00000000 --- a/openssl/trunk/doc/crypto/sha.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm - -=head1 SYNOPSIS - - #include <openssl/sha.h> - - unsigned char *SHA1(const unsigned char *d, unsigned long n, - unsigned char *md); - - void SHA1_Init(SHA_CTX *c); - void SHA1_Update(SHA_CTX *c, const void *data, - unsigned long len); - void SHA1_Final(unsigned char *md, SHA_CTX *c); - -=head1 DESCRIPTION - -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. - -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>. - -Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> -etc. instead of calling the hash functions directly. - -The predecessor of SHA-1, SHA, is also implemented, but it should be -used only when backward compatibility is required. - -=head1 RETURN VALUES - -SHA1() returns a pointer to the hash value. - -SHA1_Init(), SHA1_Update() and SHA1_Final() do not return values. - -=head1 CONFORMING TO - -SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash -Standard), -SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash -Standard), -ANSI X9.30 - -=head1 SEE ALSO - -L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all -versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/trunk/doc/crypto/threads.pod b/openssl/trunk/doc/crypto/threads.pod deleted file mode 100644 index 3df4ecd7..00000000 --- a/openssl/trunk/doc/crypto/threads.pod +++ /dev/null @@ -1,175 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks, -CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, -CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, -CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - void CRYPTO_set_locking_callback(void (*locking_function)(int mode, - int n, const char *file, int line)); - - void CRYPTO_set_id_callback(unsigned long (*id_function)(void)); - - int CRYPTO_num_locks(void); - - - /* struct CRYPTO_dynlock_value needs to be defined by the user */ - struct CRYPTO_dynlock_value; - - void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * - (*dyn_create_function)(char *file, int line)); - void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) - (int mode, struct CRYPTO_dynlock_value *l, - const char *file, int line)); - void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) - (struct CRYPTO_dynlock_value *l, const char *file, int line)); - - int CRYPTO_get_new_dynlockid(void); - - void CRYPTO_destroy_dynlockid(int i); - - void CRYPTO_lock(int mode, int n, const char *file, int line); - - #define CRYPTO_w_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_w_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_r_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_r_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_add(addr,amount,type) \ - CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) - -=head1 DESCRIPTION - -OpenSSL can safely be used in multi-threaded applications provided -that at least two callback functions are set. - -locking_function(int mode, int n, const char *file, int line) is -needed to perform locking on shared data structures. -(Note that OpenSSL uses a number of global data structures that -will be implicitly shared whenever multiple threads use OpenSSL.) -Multi-threaded applications will crash at random if it is not set. - -locking_function() must be able to handle up to CRYPTO_num_locks() -different mutex locks. It sets the B<n>-th lock if B<mode> & -B<CRYPTO_LOCK>, and releases it otherwise. - -B<file> and B<line> are the file number of the function setting the -lock. They can be useful for debugging. - -id_function(void) is a function that returns a thread ID, for example -pthread_self() if it returns an integer (see NOTES below). It isn't -needed on Windows nor on platforms where getpid() returns a different -ID for each thread (see NOTES below). - -Additionally, OpenSSL supports dynamic locks, and sometimes, some parts -of OpenSSL need it for better performance. To enable this, the following -is required: - -=over 4 - -=item * -Three additional callback function, dyn_create_function, dyn_lock_function -and dyn_destroy_function. - -=item * -A structure defined with the data that each lock needs to handle. - -=back - -struct CRYPTO_dynlock_value has to be defined to contain whatever structure -is needed to handle locks. - -dyn_create_function(const char *file, int line) is needed to create a -lock. Multi-threaded applications might crash at random if it is not set. - -dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) -is needed to perform locking off dynamic lock numbered n. Multi-threaded -applications might crash at random if it is not set. - -dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is -needed to destroy the lock l. Multi-threaded applications might crash at -random if it is not set. - -CRYPTO_get_new_dynlockid() is used to create locks. It will call -dyn_create_function for the actual creation. - -CRYPTO_destroy_dynlockid() is used to destroy locks. It will call -dyn_destroy_function for the actual destruction. - -CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield -describing what should be done with the lock. n is the number of the -lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined -from the following values. These values are pairwise exclusive, with -undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE -should not be used together): - - CRYPTO_LOCK 0x01 - CRYPTO_UNLOCK 0x02 - CRYPTO_READ 0x04 - CRYPTO_WRITE 0x08 - -=head1 RETURN VALUES - -CRYPTO_num_locks() returns the required number of locks. - -CRYPTO_get_new_dynlockid() returns the index to the newly created lock. - -The other functions return no values. - -=head1 NOTES - -You can find out if OpenSSL was configured with thread support: - - #define OPENSSL_THREAD_DEFINES - #include <openssl/opensslconf.h> - #if defined(OPENSSL_THREADS) - // thread support enabled - #else - // no thread support - #endif - -Also, dynamic locks are currently not used internally by OpenSSL, but -may do so in the future. - -Defining id_function(void) has it's own issues. Generally speaking, -pthread_self() should be used, even on platforms where getpid() gives -different answers in each thread, since that may depend on the machine -the program is run on, not the machine where the program is being -compiled. For instance, Red Hat 8 Linux and earlier used -LinuxThreads, whose getpid() returns a different value for each -thread. Red Hat 9 Linux and later use NPTL, which is -Posix-conformant, and has a getpid() that returns the same value for -all threads in a process. A program compiled on Red Hat 8 and run on -Red Hat 9 will therefore see getpid() returning the same value for -all threads. - -There is still the issue of platforms where pthread_self() returns -something other than an integer. This is a bit unusual, and this -manual has no cookbook solution for that case. - -=head1 EXAMPLES - -B<crypto/threads/mttest.c> shows examples of the callback functions on -Solaris, Irix and Win32. - -=head1 HISTORY - -CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are -available in all versions of SSLeay and OpenSSL. -CRYPTO_num_locks() was added in OpenSSL 0.9.4. -All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)> - -=cut diff --git a/openssl/trunk/doc/crypto/ui.pod b/openssl/trunk/doc/crypto/ui.pod deleted file mode 100644 index 6df68d60..00000000 --- a/openssl/trunk/doc/crypto/ui.pod +++ /dev/null @@ -1,194 +0,0 @@ -=pod - -=head1 NAME - -UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, -UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, -UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, -UI_add_error_string, UI_dup_error_string, UI_construct_prompt, -UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, -UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, -UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface - -=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); - - /* These are the possible flags. They can be or'ed together. */ - #define UI_INPUT_FLAG_ECHO 0x01 - #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 - - char *UI_construct_prompt(UI *ui_method, - const char *object_desc, const char *object_name); - - 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)()); - #define UI_CTRL_PRINT_ERRORS 1 - #define UI_CTRL_IS_REDOABLE 2 - - void UI_set_default_method(const UI_METHOD *meth); - const UI_METHOD *UI_get_default_method(void); - 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)|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. - -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. 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 really 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 UI_INPUT_FLAG_ECHO, which is relevant for -UI_add_input_string() and will have the users response be echoed (when -prompting for a password, this flag should obviously not be used, and -UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some -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: UI_CTRL_PRINT_ERRORS, which makes UI_process() -print the OpenSSL error stack as part of processing the UI, and -UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can -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 SEE ALSO - -L<ui_create(3)|ui_create(3)>, L<ui_compat(3)|ui_compat(3)> - -=head1 HISTORY - -The UI section was first introduced in OpenSSL 0.9.7. - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/openssl/trunk/doc/crypto/ui_compat.pod b/openssl/trunk/doc/crypto/ui_compat.pod deleted file mode 100644 index 9ab3c69b..00000000 --- a/openssl/trunk/doc/crypto/ui_compat.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw - -Compatibility user interface functions - -=head1 SYNOPSIS - - int des_read_password(DES_cblock *key,const char *prompt,int verify); - int des_read_2passwords(DES_cblock *key1,DES_cblock *key2, - const char *prompt,int verify); - - int des_read_pw_string(char *buf,int length,const char *prompt,int verify); - int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); - -=head1 DESCRIPTION - -The DES library contained a few routines to prompt for passwords. These -aren't necessarely dependent on DES, and have therefore become part of the -UI compatibility library. - -des_read_pw() writes the string specified by I<prompt> to standard output -turns echo off and reads an input string from the terminal. The string is -returned in I<buf>, which must have spac for at least I<size> bytes. -If I<verify> is set, the user is asked for the password twice and unless -the two copies match, an error is returned. The second password is stored -in I<buff>, which must therefore also be at least I<size> bytes. A return -code of -1 indicates a system error, 1 failure due to use interaction, and -0 is success. All other functions described here use des_read_pw() to do -the work. - -des_read_pw_string() is a variant of des_read_pw() that provides a buffer -for you if I<verify> is set. - -des_read_password() calls des_read_pw() and converts the password to a -DES key by calling DES_string_to_key(); des_read_2password() operates in -the same way as des_read_password() except that it generates two keys -by using the DES_string_to_2key() function. - -=head1 NOTES - -des_read_pw_string() is available in the MIT Kerberos library as well, and -is also available under the name EVP_read_pw_string(). - -=head1 SEE ALSO - -L<ui(3)|ui(3)>, L<ui_create(3)|ui_create(3)> - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/openssl/trunk/doc/crypto/x509.pod b/openssl/trunk/doc/crypto/x509.pod deleted file mode 100644 index f9e58e0e..00000000 --- a/openssl/trunk/doc/crypto/x509.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=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)|X509_NAME_ENTRY_get_object(3)>, -L<X509_NAME_add_entry_by_txt(3)|X509_NAME_add_entry_by_txt(3)>, -L<X509_NAME_add_entry_by_NID(3)|X509_NAME_add_entry_by_NID(3)>, -L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>, -L<X509_NAME_new(3)|X509_NAME_new(3)>, -L<d2i_X509(3)|d2i_X509(3)>, -L<d2i_X509_ALGOR(3)|d2i_X509_ALGOR(3)>, -L<d2i_X509_CRL(3)|d2i_X509_CRL(3)>, -L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, -L<d2i_X509_REQ(3)|d2i_X509_REQ(3)>, -L<d2i_X509_SIG(3)|d2i_X509_SIG(3)>, -L<crypto(3)|crypto(3)>, -L<x509v3(3)|x509v3(3)> - -=cut |