diff options
Diffstat (limited to 'openssl/doc/crypto')
| -rw-r--r-- | openssl/doc/crypto/CMS_get0_type.pod | 22 | ||||
| -rw-r--r-- | openssl/doc/crypto/CONF_modules_load_file.pod | 87 | ||||
| -rw-r--r-- | openssl/doc/crypto/OPENSSL_config.pod | 31 | ||||
| -rw-r--r-- | openssl/doc/crypto/d2i_CMS_ContentInfo.pod | 29 | ||||
| -rw-r--r-- | openssl/doc/crypto/d2i_ECPrivateKey.pod | 67 | ||||
| -rw-r--r-- | openssl/doc/crypto/d2i_X509.pod | 12 |
6 files changed, 217 insertions, 31 deletions
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/OPENSSL_config.pod b/openssl/doc/crypto/OPENSSL_config.pod index 888de88f6..5096faca0 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. 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_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 298ec54a4..e3dc23819 100644 --- a/openssl/doc/crypto/d2i_X509.pod +++ b/openssl/doc/crypto/d2i_X509.pod @@ -28,8 +28,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. @@ -210,7 +213,10 @@ always succeed. 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 |