aboutsummaryrefslogtreecommitdiffstats
path: root/doc/crypto
diff options
context:
space:
mode:
Diffstat (limited to 'doc/crypto')
-rw-r--r--doc/crypto/CMS_get0_type.pod22
-rw-r--r--doc/crypto/CONF_modules_load_file.pod87
-rw-r--r--doc/crypto/OPENSSL_config.pod31
-rw-r--r--doc/crypto/d2i_CMS_ContentInfo.pod29
-rw-r--r--doc/crypto/d2i_ECPrivateKey.pod67
-rw-r--r--doc/crypto/d2i_X509.pod12
6 files changed, 217 insertions, 31 deletions
diff --git a/doc/crypto/CMS_get0_type.pod b/doc/crypto/CMS_get0_type.pod
index 8ff1c3115cd4..3ed92bdbbe93 100644
--- a/doc/crypto/CMS_get0_type.pod
+++ b/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/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod
index 0c4d926858fb..cc0b537b8ea5 100644
--- a/doc/crypto/CONF_modules_load_file.pod
+++ b/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/doc/crypto/OPENSSL_config.pod b/doc/crypto/OPENSSL_config.pod
index 888de88f6bbf..5096faca04fc 100644
--- a/doc/crypto/OPENSSL_config.pod
+++ b/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/doc/crypto/d2i_CMS_ContentInfo.pod b/doc/crypto/d2i_CMS_ContentInfo.pod
new file mode 100644
index 000000000000..6ddb2f6d0583
--- /dev/null
+++ b/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/doc/crypto/d2i_ECPrivateKey.pod b/doc/crypto/d2i_ECPrivateKey.pod
new file mode 100644
index 000000000000..adeffe643c84
--- /dev/null
+++ b/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/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod
index 298ec54a4c3b..e3dc2381966b 100644
--- a/doc/crypto/d2i_X509.pod
+++ b/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