diff options
Diffstat (limited to 'openssl/doc/crypto')
| -rw-r--r-- | openssl/doc/crypto/ASN1_TIME_set.pod | 129 | ||||
| -rw-r--r-- | openssl/doc/crypto/CMS_get0_type.pod | 22 | ||||
| -rw-r--r-- | openssl/doc/crypto/CONF_modules_load_file.pod | 87 | ||||
| -rwxr-xr-x | openssl/doc/crypto/EC_KEY_new.pod | 22 | ||||
| -rwxr-xr-x | openssl/doc/crypto/EC_POINT_new.pod | 9 | ||||
| -rw-r--r-- | openssl/doc/crypto/OPENSSL_config.pod | 42 | ||||
| -rwxr-xr-x | openssl/doc/crypto/X509_check_host.pod | 7 | ||||
| -rw-r--r-- | openssl/doc/crypto/d2i_CMS_ContentInfo.pod | 29 | ||||
| -rwxr-xr-x | openssl/doc/crypto/d2i_ECPKParameters.pod | 2 | ||||
| -rw-r--r-- | openssl/doc/crypto/d2i_ECPrivateKey.pod | 67 | ||||
| -rw-r--r-- | openssl/doc/crypto/d2i_X509.pod | 12 | ||||
| -rw-r--r-- | openssl/doc/crypto/sha.pod | 64 |
12 files changed, 413 insertions, 79 deletions
diff --git a/openssl/doc/crypto/ASN1_TIME_set.pod b/openssl/doc/crypto/ASN1_TIME_set.pod new file mode 100644 index 000000000..ae2b53d35 --- /dev/null +++ b/openssl/doc/crypto/ASN1_TIME_set.pod @@ -0,0 +1,129 @@ +=pod + +=head1 NAME + +ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string, +ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions. + +=head1 SYNOPSIS + + ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t); + ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, + int offset_day, long offset_sec); + int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); + int ASN1_TIME_check(const ASN1_TIME *t); + int ASN1_TIME_print(BIO *b, const ASN1_TIME *s); + + int ASN1_TIME_diff(int *pday, int *psec, + const ASN1_TIME *from, const ASN1_TIME *to); + +=head1 DESCRIPTION + +The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the +time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME +structure is allocated and returned. + +ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented +by the time B<offset_day> and B<offset_sec> after the time_t value B<t>. +The values of B<offset_day> or B<offset_sec> can be negative to set a +time before B<t>. The B<offset_sec> value can also exceed the number of +seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated +and returned. + +ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time +represented by string B<str> which must be in appropriate ASN.1 time +format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). + +ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>. + +ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable +format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example +"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time +structure has invalid format it prints out "Bad time value" and returns +an error. + +ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between +B<from> and B<to>. If B<to> represents a time later than B<from> then +one or both (depending on the time difference) of B<*pday> and B<*psec> +will be positive. If B<to> represents a time earlier than B<from> then +one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from> +represent the same time then B<*pday> and B<*psec> will both be zero. +If both B<*pday> and B<*psec> are non-zero they will always have the same +sign. The value of B<*psec> will always be less than the number of seconds +in a day. If B<from> or B<to> is NULL the current time is used. + +=head1 NOTES + +The ASN1_TIME structure corresponds to the ASN.1 structure B<Time> +defined in RFC5280 et al. The time setting functions obey the rules outlined +in RFC5280: if the date can be represented by UTCTime it is used, else +GeneralizedTime is used. + +The ASN1_TIME structure is represented as an ASN1_STRING internally and can +be freed up using ASN1_STRING_free(). + +The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt +is made to correct ancient calendar changes (for example from Julian to +Gregorian calendars). + +Some applications add offset times directly to a time_t value and pass the +results to ASN1_TIME_set() (or equivalent). This can cause problems as the +time_t value can overflow on some systems resulting in unexpected results. +New applications should use ASN1_TIME_adj() instead and pass the offset value +in the B<offset_sec> and B<offset_day> parameters instead of directly +manipulating a time_t value. + +=head1 BUGS + +ASN1_TIME_print() currently does not print out the time zone: it either prints +out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT +anyway. + +=head1 EXAMPLES + +Set a time structure to one hour after the current time and print it out: + + #include <time.h> + #include <openssl/asn1.h> + ASN1_TIME *tm; + time_t t; + BIO *b; + t = time(NULL); + tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); + b = BIO_new_fp(stdout, BIO_NOCLOSE); + ASN1_TIME_print(b, tm); + ASN1_STRING_free(tm); + BIO_free(b); + +Determine if one time is later or sooner than the current time: + + int day, sec; + + if (!ASN1_TIME_diff(&day, &sec, NULL, to)) + /* Invalid time format */ + + if (day > 0 || sec > 0) + printf("Later\n"); + else if (day < 0 || sec < 0) + printf("Sooner\n"); + else + printf("Same\n"); + +=head1 RETURN VALUES + +ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure +or NULL if an error occurred. + +ASN1_TIME_set_string() returns 1 if the time value is successfully set and +0 otherwise. + +ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0 +otherwise. + +ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if +an error occurred (I/O error or invalid time format). + +ASN1_TIME_diff() returns 1 for sucess and 0 for failure. It can fail if the +pass ASN1_TIME structure has invalid syntax for example. + +=cut diff --git a/openssl/doc/crypto/CMS_get0_type.pod b/openssl/doc/crypto/CMS_get0_type.pod index 8ff1c3115..3ed92bdbb 100644 --- a/openssl/doc/crypto/CMS_get0_type.pod +++ b/openssl/doc/crypto/CMS_get0_type.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types + CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content =head1 SYNOPSIS @@ -11,6 +11,7 @@ const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms); int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid); const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms); + ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms); =head1 DESCRIPTION @@ -26,11 +27,15 @@ undefined. ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded content type. +CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer +containing the embedded content. + =head1 NOTES -As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal -pointers which should B<not> be freed up. CMS_set1_eContentType() copies the -supplied OID and it B<should> be freed up after use. +As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and +CMS_get0_content() return internal pointers which should B<not> be freed up. +CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up +after use. The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value using OBJ_obj2nid(). For the currently supported content types the following @@ -43,6 +48,15 @@ values are returned: NID_pkcs7_encrypted NID_pkcs7_enveloped +The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING> +content pointer. That means that for example: + + ASN1_OCTET_STRING **pconf = CMS_get0_content(cms); + +B<*pconf> could be NULL if there is no embedded content. Applications can +access, modify or create the embedded content in a B<CMS_ContentInfo> structure +using this function. Applications usually will not need to modify the +embedded content as it is normally set by higher level functions. =head1 RETURN VALUES diff --git a/openssl/doc/crypto/CONF_modules_load_file.pod b/openssl/doc/crypto/CONF_modules_load_file.pod index 0c4d92685..cc0b537b8 100644 --- a/openssl/doc/crypto/CONF_modules_load_file.pod +++ b/openssl/doc/crypto/CONF_modules_load_file.pod @@ -9,9 +9,9 @@ #include <openssl/conf.h> int CONF_modules_load_file(const char *filename, const char *appname, - unsigned long flags); + unsigned long flags); int CONF_modules_load(const CONF *cnf, const char *appname, - unsigned long flags); + unsigned long flags); =head1 DESCRIPTION @@ -22,7 +22,7 @@ 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>. +reads configuration information from B<cnf>. =head1 NOTES @@ -30,7 +30,7 @@ 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. +considered fatal and no further modules are loaded. Normally any modules errors will add error information to the error queue. If B<CONF_MFLAGS_SILENT> is set no error information is added. @@ -42,7 +42,84 @@ 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 +B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the +default section pointed to by B<openssl_conf> if B<appname> does not exist. + +Applications should call these functions after loading builtin modules using +OPENSSL_load_builtin_modules(), any ENGINEs for example using +ENGINE_load_builtin_engines(), any algorithms for example +OPENSSL_add_all_algorithms() and (if the application uses libssl) +SSL_library_init(). + +By using CONF_modules_load_file() with appropriate flags an application can +customise application configuration to best suit its needs. In some cases the +use of a configuration file is optional and its absence is not an error: in +this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set. + +Errors during configuration may also be handled differently by different +applications. For example in some cases an error may simply print out a warning +message and the application continue. In other cases an application might +consider a configuration file error as fatal and exit immediately. + +Applications can use the CONF_modules_load() function if they wish to load a +configuration file themselves and have finer control over how errors are +treated. + +=head1 EXAMPLES + +Load a configuration file and print out any errors and exit (missing file +considered fatal): + + if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load default configuration file using the section indicated by "myapp", +tolerate missing files, but exit on other errors: + + if (CONF_modules_load_file(NULL, "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load custom configuration file and section, only print warnings on error, +missing configuration file ignored: + + if (CONF_modules_load_file("/something/app.cnf", "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "WARNING: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + } + +Load and parse configuration file manually, custom error handling: + + FILE *fp; + CONF *cnf = NULL; + long eline; + fp = fopen("/somepath/app.cnf", "r"); + if (fp == NULL) { + fprintf(stderr, "Error opening configuration file\n"); + /* Other missing configuration file behaviour */ + } else { + cnf = NCONF_new(NULL); + if (NCONF_load_fp(cnf, fp, &eline) == 0) { + fprintf(stderr, "Error on line %ld of configuration file\n", eline); + ERR_print_errors_fp(stderr); + /* Other malformed configuration file behaviour */ + } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { + fprintf(stderr, "Error configuring application\n"); + ERR_print_errors_fp(stderr); + /* Other configuration error behaviour */ + } + fclose(fp); + NCONF_free(cnf); + } + +=head1 RETURN VALUES These functions return 1 for success and a zero or negative value for failure. If module errors are not ignored the return code will reflect the diff --git a/openssl/doc/crypto/EC_KEY_new.pod b/openssl/doc/crypto/EC_KEY_new.pod index 2027569f4..e859689bc 100755 --- a/openssl/doc/crypto/EC_KEY_new.pod +++ b/openssl/doc/crypto/EC_KEY_new.pod @@ -24,8 +24,6 @@ EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_b int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); - unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); void *EC_KEY_get_key_method_data(EC_KEY *key, @@ -69,16 +67,6 @@ on the key to confirm that it is valid. The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B<key> respectively. -The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the value of the encoding flags for the B<key>. There are two encoding -flags currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags define the behaviour of how the B<key> is -converted into ASN1 in a call to i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for the curve are not encoded -along with the private key. If EC_PKEY_NO_PUBKEY is set then the public key is not encoded along with the private key. - -When reading a private key encoded with EC_PKEY_NO_PUBKEY, -d2i_ECPrivateKey generates the missing public key -automatically. Private keys encoded with EC_PKEY_NO_PARAMETERS cannot -be loaded using d2i_ECPrivateKey. - The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B<key>. For a description of point_conversion_forms please refer to L<EC_POINT_new(3)|EC_POINT_new(3)>. @@ -106,15 +94,15 @@ EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY. EC_KEY_get0_private_key returns the private key associated with the EC_KEY. -EC_KEY_get_enc_flags returns the value of the current encoding flags for the EC_KEY. - EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY. =head1 SEE ALSO -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> +L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, +L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>, +L<EC_POINT_add(3)|EC_POINT_add(3)>, +L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, +L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> =cut diff --git a/openssl/doc/crypto/EC_POINT_new.pod b/openssl/doc/crypto/EC_POINT_new.pod index 69eb0d1a0..858baf424 100755 --- a/openssl/doc/crypto/EC_POINT_new.pod +++ b/openssl/doc/crypto/EC_POINT_new.pod @@ -81,8 +81,13 @@ on the curve there will only ever be two possible values for y. Therefore a poin and EC_POINT_set_compressed_coordinates_GF2m functions where B<x> is the x co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two possible values for y should be used. -In addition EC_POINTs can be converted to and from various external representations. Supported representations are octet strings, BIGNUMs and hexadecimal. The format of the external representation is described by the point_conversion_form. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for -a description of point_conversion_form. Octet strings are stored in a buffer along with an associated buffer length. A point held in a BIGNUM is calculated by converting the point to an octet string and then converting that octet string into a BIGNUM integer. Points in hexadecimal format are stored in a NULL terminated character string where each character is one of the printable values 0-9 or A-F (or a-f). +In addition EC_POINTs can be converted to and from various external +representations. Supported representations are octet strings, BIGNUMs and +hexadecimal. Octet strings are stored in a buffer along with an associated +buffer length. A point held in a BIGNUM is calculated by converting the point to +an octet string and then converting that octet string into a BIGNUM integer. +Points in hexadecimal format are stored in a NULL terminated character string +where each character is one of the printable values 0-9 or A-F (or a-f). The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively. diff --git a/openssl/doc/crypto/OPENSSL_config.pod b/openssl/doc/crypto/OPENSSL_config.pod index 888de88f6..2d25b2669 100644 --- a/openssl/doc/crypto/OPENSSL_config.pod +++ b/openssl/doc/crypto/OPENSSL_config.pod @@ -15,31 +15,24 @@ OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions 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. +the file specified in the environment variable B<OPENSSL_CONF> will be used, +and if that is not set then a system default location is used. +Errors are silently ignored. +Multiple calls have no effect. 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. +The OPENSSL_config() function is designed to be a very simple "call it and +forget it" function. +It is however B<much> better than nothing. Applications which need finer +control over their configuration functionality should use the configuration +functions such as CONF_modules_load() directly. This function is deprecated +and its use should be avoided. +Applications should instead call CONF_modules_load() during +initialization (that is before starting any threads). There are several reasons why calling the OpenSSL configuration routines is advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7. @@ -55,17 +48,6 @@ 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. diff --git a/openssl/doc/crypto/X509_check_host.pod b/openssl/doc/crypto/X509_check_host.pod index f8b530df9..0def17aac 100755 --- a/openssl/doc/crypto/X509_check_host.pod +++ b/openssl/doc/crypto/X509_check_host.pod @@ -109,9 +109,12 @@ but would not match a peer certificate with a DNS name of =head1 RETURN VALUES The functions return 1 for a successful match, 0 for a failed match -and -1 for an internal error: typically a memory allocation failure. +and -1 for an internal error: typically a memory allocation failure +or an ASN.1 decoding error. -X509_check_ip_asc() can also return -2 if the IP address string is malformed. +All functions can also return -2 if the input is malformed. For example, +X509_check_host() returns -2 if the provided B<name> contains embedded +NULs. =head1 NOTES diff --git a/openssl/doc/crypto/d2i_CMS_ContentInfo.pod b/openssl/doc/crypto/d2i_CMS_ContentInfo.pod new file mode 100644 index 000000000..6ddb2f6d0 --- /dev/null +++ b/openssl/doc/crypto/d2i_CMS_ContentInfo.pod @@ -0,0 +1,29 @@ +=pod + +=head1 NAME + +d2i_CMS_ContentInfo, i2d_CMS_ContentInfo - CMS ContentInfo functions + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *d2i_CMS_ContentInfo(CMS_ContentInfo **a, unsigned char **pp, long length); + int i2d_CMS_ContentInfo(CMS_ContentInfo *a, unsigned char **pp); + +=head1 DESCRIPTION + +These functions decode and encode an CMS ContentInfo structure. + +Otherwise they behave in a similar way to d2i_X509() and i2d_X509() +described in the L<d2i_X509(3)|d2i_X509(3)> manual page. + +=head1 SEE ALSO + +L<d2i_X509(3)|d2i_X509(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/d2i_ECPKParameters.pod b/openssl/doc/crypto/d2i_ECPKParameters.pod index 3768c410d..704b4ab35 100755 --- a/openssl/doc/crypto/d2i_ECPKParameters.pod +++ b/openssl/doc/crypto/d2i_ECPKParameters.pod @@ -2,7 +2,7 @@ =head1 NAME -d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp(fp,x), ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities +d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities =head1 SYNOPSIS diff --git a/openssl/doc/crypto/d2i_ECPrivateKey.pod b/openssl/doc/crypto/d2i_ECPrivateKey.pod new file mode 100644 index 000000000..adeffe643 --- /dev/null +++ b/openssl/doc/crypto/d2i_ECPrivateKey.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + +i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and +reading EC_KEY structures + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); + int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); + + unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); + void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); + +=head1 DESCRIPTION + +The ECPrivateKey encode and decode routines encode and parse an +B<EC_KEY> structure into a binary format (ASN.1 DER) and back again. + +These functions are similar to the d2i_X509() functions, and you should refer to +that page for a detailed description (see L<d2i_X509(3)|d2i_X509(3)>). + +The format of the external representation of the public key written by +i2d_ECPrivateKey (such as whether it is stored in a compressed form or not) is +described by the point_conversion_form. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> +for a description of point_conversion_form. + +When reading a private key encoded without an associated public key (e.g. if +EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey generates +the missing public key automatically. Private keys encoded without parameters +(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using +d2i_ECPrivateKey. + +The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the +value of the encoding flags for the B<key>. There are two encoding flags +currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags +define the behaviour of how the B<key> is converted into ASN1 in a call to +i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for +the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is +set then the public key is not encoded along with the private key. + +=head1 RETURN VALUES + +d2i_ECPrivateKey() returns a valid B<EC_KEY> structure or B<NULL> if an error +occurs. The error code that can be obtained by +L<ERR_get_error(3)|ERR_get_error(3)>. + +i2d_ECPrivateKey() returns the number of bytes successfully encoded or a +negative value if an error occurs. The error code can be obtained by +L<ERR_get_error(3)|ERR_get_error(3)>. + +EC_KEY_get_enc_flags returns the value of the current encoding flags for the +EC_KEY. + +=head1 SEE ALSO + +L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, +L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>, +L<EC_POINT_add(3)|EC_POINT_add(3)>, +L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, +L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>, +L<d2i_ECPrivateKey(3)|d2i_ECPrivateKey(3)> + +=cut diff --git a/openssl/doc/crypto/d2i_X509.pod b/openssl/doc/crypto/d2i_X509.pod index fea6e868e..5b7c16fd0 100644 --- a/openssl/doc/crypto/d2i_X509.pod +++ b/openssl/doc/crypto/d2i_X509.pod @@ -30,8 +30,11 @@ 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 +structure and an attempt is made to reuse it. This "reuse" capability is present +for historical compatibility but its use is B<strongly discouraged> (see BUGS +below, and the discussion in the RETURN VALUES section). + +If the call is successful B<*in> is incremented to the byte following the parsed data. i2d_X509() encodes the structure pointed to by B<x> into DER format. @@ -233,7 +236,10 @@ i2d_re_X509_tbs(). 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)>. +L<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used +with a valid X509 structure being passed in via B<px> then the object is not +freed in the event of error but may be in a potentially invalid or inconsistent +state. i2d_X509() returns the number of bytes successfully encoded or a negative value if an error occurs. The error code can be obtained by diff --git a/openssl/doc/crypto/sha.pod b/openssl/doc/crypto/sha.pod index 94ab7bc72..0c9dbf2f3 100644 --- a/openssl/doc/crypto/sha.pod +++ b/openssl/doc/crypto/sha.pod @@ -2,29 +2,58 @@ =head1 NAME -SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm +SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update, +SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384, +SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update, +SHA512_Final - Secure Hash Algorithm =head1 SYNOPSIS #include <openssl/sha.h> - unsigned char *SHA1(const unsigned char *d, unsigned long n, - unsigned char *md); - int SHA1_Init(SHA_CTX *c); - int SHA1_Update(SHA_CTX *c, const void *data, - unsigned long len); + int SHA1_Update(SHA_CTX *c, const void *data, size_t len); int SHA1_Final(unsigned char *md, SHA_CTX *c); + unsigned char *SHA1(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA224_Init(SHA256_CTX *c); + int SHA224_Update(SHA256_CTX *c, const void *data, size_t len); + int SHA224_Final(unsigned char *md, SHA256_CTX *c); + unsigned char *SHA224(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA256_Init(SHA256_CTX *c); + int SHA256_Update(SHA256_CTX *c, const void *data, size_t len); + int SHA256_Final(unsigned char *md, SHA256_CTX *c); + unsigned char *SHA256(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA384_Init(SHA512_CTX *c); + int SHA384_Update(SHA512_CTX *c, const void *data, size_t len); + int SHA384_Final(unsigned char *md, SHA512_CTX *c); + unsigned char *SHA384(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA512_Init(SHA512_CTX *c); + int SHA512_Update(SHA512_CTX *c, const void *data, size_t len); + int SHA512_Final(unsigned char *md, SHA512_CTX *c); + unsigned char *SHA512(const unsigned char *d, size_t n, + unsigned char *md); =head1 DESCRIPTION +Applications should use the higher level functions +L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the hash +functions directly. + SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a 160 bit output. SHA1() computes the SHA-1 message digest of the B<n> bytes at B<d> and places it in B<md> (which must have space for SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest -is placed in a static array. +is placed in a static array. Note: setting B<md> to NULL is B<not thread safe>. The following functions may be used if the message is not completely stored in memory: @@ -37,24 +66,29 @@ 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 SHA224, SHA256, SHA384 and SHA512 families of functions operate in the +same way as for the SHA1 functions. Note that SHA224 and SHA256 use a +B<SHA256_CTX> object instead of B<SHA_CTX>. SHA384 and SHA512 use B<SHA512_CTX>. +The buffer B<md> must have space for the output from the SHA variant being used +(defined by SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH and +SHA512_DIGEST_LENGTH). Also note that, as for the SHA1() function above, the +SHA224(), SHA256(), SHA384() and SHA512() functions are not thread safe if +B<md> is NULL. The predecessor of SHA-1, SHA, is also implemented, but it should be used only when backward compatibility is required. =head1 RETURN VALUES -SHA1() returns a pointer to the hash value. +SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash +value. -SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise. +SHA1_Init(), SHA1_Update() and SHA1_Final() and equivalent SHA224, SHA256, +SHA384 and SHA512 functions return 1 for success, 0 otherwise. =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 +US Federal Information Processing Standard FIPS PUB 180-4 (Secure Hash Standard), ANSI X9.30 |