From 829fd51d4f8dde4a7f3bf54754f3c1d1a502f5e2 Mon Sep 17 00:00:00 2001 From: djm <> Date: Fri, 1 Oct 2010 22:54:21 +0000 Subject: import OpenSSL-1.0.0a --- src/lib/libcrypto/doc/DSA_get_ex_new_index.pod | 2 +- src/lib/libcrypto/doc/EVP_DigestInit.pod | 23 +- src/lib/libcrypto/doc/EVP_DigestSignInit.pod | 87 ++++++ src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod | 82 ++++++ src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod | 128 +++++++++ src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod | 52 ++++ src/lib/libcrypto/doc/EVP_PKEY_cmp.pod | 61 +++++ src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod | 93 +++++++ src/lib/libcrypto/doc/EVP_PKEY_derive.pod | 93 +++++++ src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod | 93 +++++++ .../libcrypto/doc/EVP_PKEY_get_default_digest.pod | 41 +++ src/lib/libcrypto/doc/EVP_PKEY_keygen.pod | 161 +++++++++++ src/lib/libcrypto/doc/EVP_PKEY_print_private.pod | 53 ++++ src/lib/libcrypto/doc/EVP_PKEY_sign.pod | 96 +++++++ src/lib/libcrypto/doc/EVP_PKEY_verify.pod | 91 +++++++ src/lib/libcrypto/doc/EVP_SignInit.pod | 9 + src/lib/libcrypto/doc/EVP_VerifyInit.pod | 9 + src/lib/libcrypto/doc/OBJ_nid2obj.pod | 2 + src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod | 41 +++ .../libcrypto/doc/PEM_write_bio_PKCS7_stream.pod | 41 +++ src/lib/libcrypto/doc/PKCS12_parse.pod | 31 ++- src/lib/libcrypto/doc/PKCS7_decrypt.pod | 4 +- src/lib/libcrypto/doc/PKCS7_encrypt.pod | 61 +++-- src/lib/libcrypto/doc/PKCS7_sign.pod | 115 ++++---- src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod | 87 ++++++ src/lib/libcrypto/doc/PKCS7_verify.pod | 6 +- src/lib/libcrypto/doc/SMIME_read_CMS.pod | 70 +++++ src/lib/libcrypto/doc/SMIME_read_PKCS7.pod | 4 +- src/lib/libcrypto/doc/SMIME_write_CMS.pod | 64 +++++ src/lib/libcrypto/doc/SMIME_write_PKCS7.pod | 24 +- .../libcrypto/doc/X509_NAME_ENTRY_get_object.pod | 16 +- .../libcrypto/doc/X509_NAME_add_entry_by_txt.pod | 12 +- .../libcrypto/doc/X509_NAME_get_index_by_NID.pod | 14 +- src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod | 303 +++++++++++++++++++++ .../doc/X509_STORE_CTX_get_ex_new_index.pod | 41 +++ src/lib/libcrypto/doc/X509_STORE_CTX_new.pod | 122 +++++++++ .../libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod | 161 +++++++++++ .../doc/X509_STORE_set_verify_cb_func.pod | 54 ++++ .../libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod | 171 ++++++++++++ src/lib/libcrypto/doc/X509_new.pod | 2 + src/lib/libcrypto/doc/X509_verify_cert.pod | 53 ++++ src/lib/libcrypto/doc/d2i_RSAPublicKey.pod | 8 +- src/lib/libcrypto/doc/d2i_X509.pod | 12 +- src/lib/libcrypto/doc/d2i_X509_CRL.pod | 4 +- src/lib/libcrypto/doc/d2i_X509_REQ.pod | 4 +- src/lib/libcrypto/doc/evp.pod | 22 +- src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod | 44 +++ src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod | 44 +++ 48 files changed, 2663 insertions(+), 148 deletions(-) create mode 100644 src/lib/libcrypto/doc/EVP_DigestSignInit.pod create mode 100644 src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_cmp.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_derive.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_keygen.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_print_private.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_sign.pod create mode 100644 src/lib/libcrypto/doc/EVP_PKEY_verify.pod create mode 100644 src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod create mode 100644 src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod create mode 100644 src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod create mode 100644 src/lib/libcrypto/doc/SMIME_read_CMS.pod create mode 100644 src/lib/libcrypto/doc/SMIME_write_CMS.pod create mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod create mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod create mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_new.pod create mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod create mode 100644 src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod create mode 100644 src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod create mode 100644 src/lib/libcrypto/doc/X509_verify_cert.pod create mode 100644 src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod create mode 100644 src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod (limited to 'src/lib/libcrypto/doc') diff --git a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod index 4612e708ec..fb6efc1182 100644 --- a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod +++ b/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod @@ -6,7 +6,7 @@ DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specifi =head1 SYNOPSIS - #include + #include int DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, diff --git a/src/lib/libcrypto/doc/EVP_DigestInit.pod b/src/lib/libcrypto/doc/EVP_DigestInit.pod index 130cd7f60a..5b477ac6ec 100644 --- a/src/lib/libcrypto/doc/EVP_DigestInit.pod +++ b/src/lib/libcrypto/doc/EVP_DigestInit.pod @@ -64,9 +64,9 @@ EVP digest routines The EVP digest routines are a high level interface to message digests. -EVP_MD_CTX_init() initializes digest contet B. +EVP_MD_CTX_init() initializes digest context B. -EVP_MD_CTX_create() allocates, initializes and returns a digest contet. +EVP_MD_CTX_create() allocates, initializes and returns a digest context. EVP_DigestInit_ex() sets up digest context B to use a digest B from ENGINE B. B must be initialized before calling this @@ -102,7 +102,7 @@ the passed context B 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 is automatically cleaned up. +context B is automatically cleaned up. EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination B does not have to be initialized. @@ -132,7 +132,9 @@ return B structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 dige algorithms respectively. The associated signature algorithm is RSA in each case. EVP_dss() and EVP_dss1() return B structures for SHA and SHA1 digest -algorithms but using DSS (DSA) for the signature algorithm. +algorithms but using DSS (DSA) for the signature algorithm. Note: there is +no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are +however retained for compatibility. EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it returns is of zero length. @@ -228,12 +230,6 @@ digest name passed on the command line. 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, L, L, @@ -253,4 +249,11 @@ 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. +The link between digests and signing algorithms was fixed in OpenSSL 1.0 and +later, so now EVP_sha1() can be used with RSA and DSA, there is no need to +use EVP_dss1() any more. + +OpenSSL 1.0 and later does not include the MD2 digest algorithm in the +default configuration due to its security weaknesses. + =cut diff --git a/src/lib/libcrypto/doc/EVP_DigestSignInit.pod b/src/lib/libcrypto/doc/EVP_DigestSignInit.pod new file mode 100644 index 0000000000..37d960e3b2 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_DigestSignInit.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions + +=head1 SYNOPSIS + + #include + + int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital signatures. + +EVP_DigestSignInit() sets up signing context B to use digest B from +ENGINE B and private key B. B must be initialized with +EVP_MD_CTX_init() before calling this function. If B is not NULL the +EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can +be used to set alternative signing options. + +EVP_DigestSignUpdate() hashes B bytes of data at B into the +signature context B. This function can be called several times on the +same B to include additional data. This function is currently implemented +usig a macro. + +EVP_DigestSignFinal() signs the data in B places the signature in B. +If B is B then the maximum size of the output buffer is written to +the B parameter. If B is not B then before the call the +B parameter should contain the length of the B buffer, if the +call is successful the signature is written to B and the amount of data +written to B. + +=head1 RETURN VALUES + +EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return +1 for success and 0 or a negative value for failure. In particular a return +value of -2 indicates the operation is not supported by the public key +algorithm. + +The error codes can be obtained from L. + +=head1 NOTES + +The B interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as EVP_dss1() +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. + +For some key types and parameters the random number generator must be seeded +or the operation will fail. + +The call to EVP_DigestSignFinal() internally finalizes a copy of the digest +context. This means that calls to EVP_DigestSignUpdate() and +EVP_DigestSignFinal() can be called later to digest and sign additional data. + +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak +will occur. + +The use of EVP_PKEY_size() with these functions is discouraged because some +signature operations may have a signature length which depends on the +parameters set. As a result EVP_PKEY_size() would have to return a value +which indicates the maximum possible signature for any set of parameters. + +=head1 SEE ALSO + +L, +L, L, +L, L, L, +L, L, L, +L, L + +=head1 HISTORY + +EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() +were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod b/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod new file mode 100644 index 0000000000..f224488978 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signature verification functions + +=head1 SYNOPSIS + + #include + + int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital signatures. + +EVP_DigestVerifyInit() sets up verification context B to use digest +B from ENGINE B and public key B. B must be initialized +with EVP_MD_CTX_init() before calling this function. If B is not NULL the +EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this +can be used to set alternative verification options. + +EVP_DigestVerifyUpdate() hashes B bytes of data at B into the +verification context B. This function can be called several times on the +same B to include additional data. This function is currently implemented +using a macro. + +EVP_DigestVerifyFinal() verifies the data in B against the signature in +B of length B. + +=head1 RETURN VALUES + +EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 indicates +the operation is not supported by the public key algorithm. + +Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only +indicates that the signature did not not verify successfully (that is tbs did +not match the original data or the signature was of invalid form) it is not an +indication of a more serious error. + +The error codes can be obtained from L. + +=head1 NOTES + +The B interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as EVP_dss1() +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. + +For some key types and parameters the random number generator must be seeded +or the operation will fail. + +The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest +context. This means that 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 SEE ALSO + +L, +L, L, +L, L, L, +L, L, L, +L, L + +=head1 HISTORY + +EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() +were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod new file mode 100644 index 0000000000..f2f455990f --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +EVP_PKEY_ctrl, EVP_PKEY_ctrl_str - algorithm specific control operations + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, + int cmd, int p1, void *p2); + int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, + const char *value); + + int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); + + #include + + int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + + int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); + int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); + int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); + + #include + int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); + + #include + int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); + + #include + int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); + +=head1 DESCRIPTION + +The function EVP_PKEY_CTX_ctrl() sends a control operation to the context +B. The key type used must match B if it is not -1. The parameter +B is a mask indicating which operations the control can be applied to. +The control command is indicated in B and any additional arguments in +B and B. + +Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will +instead call one of the algorithm specific macros below. + +The function EVP_PKEY_ctrl_str() allows an application to send an algorithm +specific control operation to a context B in string form. This is +intended to be used for options specified on the command line or in text +files. The commands supported are documented in the openssl utility +command line pages for the option B<-pkeyopt> which is supported by the +B, B and B commands. + +All the remaining "functions" are implemented as macros. + +The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used +in a signature. It can be used with any public key algorithm supporting +signature operations. + +The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B. +The B parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, +RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, +RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), +RSA_X931_PADDING for X9.31 padding (signature operations only) and +RSA_PKCS1_PSS_PADDING (sign and verify only). + +Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() +is used. If this macro is called for PKCS#1 padding the plaintext buffer is +an actual digest value and is encapsulated in a DigestInfo structure according +to PKCS#1 when signing and this structure is expected (and stripped off) when +verifying. If this control is not used with RSA and PKCS#1 padding then the +supplied data is used directly and not encapsulated. In the case of X9.31 +padding for RSA the algorithm identifier byte is added or checked and removed +if this control is called. If it is not called then the first byte of the plaintext buffer is expected to be the algorithm identifier byte. + +The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to +B as its name implies it is only supported for PSS padding. Two special +values are supported: -1 sets the salt length to the digest length. When +signing -2 sets the salt length to the maximum permissible value. When +verifying -2 causes the salt length to be automatically determined based on the +B block structure. If this macro is not called a salt length value of -2 +is used by default. + +The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for +RSA key genration to B. If not specified 1024 bits is used. + +The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value +for RSA key generation to B currently it should be an odd integer. The +B pointer is used internally by this function so it should not be +modified or free after the call. If this macro is not called then 65537 is used. + +The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used +for DSA parameter generation to B. If not specified 1024 is used. + +The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH +prime parameter B

for DH parameter generation. If this macro is not called +then 1024 is used. + +The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B +for DH parameter generation. If not specified 2 is used. + +The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter +generation to B. For EC parameter generation this macro must be called +or an error occurs because there is no default curve. + +=head1 RETURN VALUES + +EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod new file mode 100644 index 0000000000..a9af867580 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions. + +=head1 SYNOPSIS + + #include + + EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); + EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); + EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); + void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); + +=head1 DESCRIPTION + +The EVP_PKEY_CTX_new() function allocates public key algorithm context using +the algorithm specified in B and ENGINE B. + +The EVP_PKEY_CTX_new_id() function allocates public key algorithm context +using the algorithm specified by B and ENGINE B. It is normally used +when no B structure is associated with the operations, for example +during parameter generation of key genration for some algorithms. + +EVP_PKEY_CTX_dup() duplicates the context B. + +EVP_PKEY_CTX_free() frees up the context B. + +=head1 NOTES + +The B structure is an opaque public key algorithm context used +by the OpenSSL high level public key API. Contexts B be shared between +threads: that is it is not permissible to use the same context simultaneously +in two threads. + +=head1 RETURN VALUES + +EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either +the newly allocated B structure of B if an error occurred. + +EVP_PKEY_CTX_free() does not return a value. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod b/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod new file mode 100644 index 0000000000..4f8185e36c --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, EVP_PKEY_cmp - public key parameter and comparison functions + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); + int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); + + int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); + int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); + +=head1 DESCRIPTION + +The function EVP_PKEY_missing_parameters() returns 1 if the public key +parameters of B are missing and 0 if they are present or the algorithm +doesn't use parameters. + +The function EVP_PKEY_copy_parameters() copies the parameters from key +B to key B. + +The funcion EVP_PKEY_cmp_parameters() compares the parameters of keys +B and B. + +The funcion EVP_PKEY_cmp() compares the public key components and paramters +(if present) of keys B and B. + +=head1 NOTES + +The main purpose of the functions EVP_PKEY_missing_parameters() and +EVP_PKEY_copy_parameters() is to handle public keys in certificates where the +parameters are sometimes omitted from a public key if they are inherited from +the CA that signed it. + +Since OpenSSL private keys contain public key components too the function +EVP_PKEY_cmp() can also be used to determine if a private key matches +a public key. + +=head1 RETURN VALUES + +The function EVP_PKEY_missing_parameters() returns 1 if the public key +parameters of B are missing and 0 if they are present or the algorithm +doesn't use parameters. + +These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for +failure. + +The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the +keys match, 0 if they don't match, -1 if the key types are different and +-2 if the operation is not supported. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod new file mode 100644 index 0000000000..42b2a8c44e --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, + unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); + +=head1 DESCRIPTION + +The EVP_PKEY_decrypt_init() function initializes a public key algorithm +context using key B for a decryption operation. + +The EVP_PKEY_decrypt() function performs a public key decryption operation +using B. The data to be decrypted is specified using the B and +B parameters. If B is B then the maximum size of the output +buffer is written to the B parameter. If B is not B then +before the call the B parameter should contain the length of the +B buffer, if the call is successful the decrypted data is written to +B and the amount of data written to B. + +=head1 NOTES + +After the call to EVP_PKEY_decrypt_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_decrypt() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Decrypt data using OAEP (for RSA keys): + + #include + #include + + EVP_PKEY_CTX *ctx; + unsigned char *out, *in; + size_t outlen, inlen; + EVP_PKEY *key; + /* NB: assumes key in, inlen are already set up + * and that key is an RSA private key + */ + ctx = EVP_PKEY_CTX_new(key); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_decrypt_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0) + /* Error */ + + out = OPENSSL_malloc(outlen); + + if (!out) + /* malloc failure */ + + if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0) + /* Error */ + + /* Decrypted data is outlen bytes written to buffer out */ + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_derive.pod b/src/lib/libcrypto/doc/EVP_PKEY_derive.pod new file mode 100644 index 0000000000..d9d6d76c72 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_derive.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret. + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); + int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); + +=head1 DESCRIPTION + +The EVP_PKEY_derive_init() function initializes a public key algorithm +context using key B for shared secret derivation. + +The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally +be a public key. + +The EVP_PKEY_derive() derives a shared secret using B. +If B is B then the maximum size of the output buffer is written to +the B parameter. If B is not B then before the call the +B parameter should contain the length of the B buffer, if the call +is successful the shared secret is written to B and the amount of data +written to B. + +=head1 NOTES + +After the call to EVP_PKEY_derive_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_derive() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Derive shared secret (for example DH or EC keys): + + #include + #include + + EVP_PKEY_CTX *ctx; + unsigned char *skey; + size_t skeylen; + EVP_PKEY *pkey, *peerkey; + /* NB: assumes pkey, peerkey have been already set up */ + + ctx = EVP_PKEY_CTX_new(pkey); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_derive_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) + /* Error */ + + skey = OPENSSL_malloc(skeylen); + + if (!skey) + /* malloc failure */ + + if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) + /* Error */ + + /* Shared secret is skey bytes written to buffer skey */ + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod new file mode 100644 index 0000000000..91c9c5d0a5 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, + unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); + +=head1 DESCRIPTION + +The EVP_PKEY_encrypt_init() function initializes a public key algorithm +context using key B for an encryption operation. + +The EVP_PKEY_encrypt() function performs a public key encryption operation +using B. The data to be encrypted is specified using the B and +B parameters. If B is B then the maximum size of the output +buffer is written to the B parameter. If B is not B then +before the call the B parameter should contain the length of the +B buffer, if the call is successful the encrypted data is written to +B and the amount of data written to B. + +=head1 NOTES + +After the call to EVP_PKEY_encrypt_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_encrypt() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Encrypt data using OAEP (for RSA keys): + + #include + #include + + EVP_PKEY_CTX *ctx; + unsigned char *out, *in; + size_t outlen, inlen; + EVP_PKEY *key; + /* NB: assumes key in, inlen are already set up + * and that key is an RSA public key + */ + ctx = EVP_PKEY_CTX_new(key); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_encrypt_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0) + /* Error */ + + out = OPENSSL_malloc(outlen); + + if (!out) + /* malloc failure */ + + if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0) + /* Error */ + + /* Encrypted data is outlen bytes written to buffer out */ + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod b/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod new file mode 100644 index 0000000000..1a9c7954c5 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +EVP_PKEY_get_default_digest_nid - get default signature digest + +=head1 SYNOPSIS + + #include + int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); + +=head1 DESCRIPTION + +The EVP_PKEY_get_default_digest_nid() function sets B to the default +message digest NID for the public key signature operations associated with key +B. + +=head1 NOTES + +For all current standard OpenSSL public key algorithms SHA1 is returned. + +=head1 RETURN VALUES + +The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest +is advisory (that is other digests can be used) and 2 if it is mandatory (other +digests can not be used). It returns 0 or a negative value for failure. In +particular a return value of -2 indicates the operation is not supported by the +public key algorithm. + +=head1 SEE ALSO + +L, +L, +L, +L, + +=head1 HISTORY + +This function was first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod b/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod new file mode 100644 index 0000000000..37c6fe9503 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod @@ -0,0 +1,161 @@ +=pod + +=head1 NAME + +EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data - key and parameter generation functions + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); + int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); + + typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); + + void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); + EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); + + int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); + + void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); + void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); + +=head1 DESCRIPTION + +The EVP_PKEY_keygen_init() function initializes a public key algorithm +context using key B for a key genration operation. + +The EVP_PKEY_keygen() function performs a key generation operation, the +generated key is written to B. + +The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar +except parameters are generated. + +The function EVP_PKEY_set_cb() sets the key or parameter generation callback +to B. The function EVP_PKEY_CTX_get_cb() returns the key or parameter +generation callback. + +The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated +with the generation operation. If B is -1 the total number of +parameters available is returned. Any non negative value returns the value of +that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for +B should only be called within the generation callback. + +If the callback returns 0 then the key genration operation is aborted and an +error occurs. This might occur during a time consuming operation where +a user clicks on a "cancel" button. + +The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set +and retrieve an opaque pointer. This can be used to set some application +defined value which can be retrieved in the callback: for example a handle +which is used to update a "progress dialog". + +=head1 NOTES + +After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm +specific control operations can be performed to set any appropriate parameters +for the operation. + +The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than +once on the same context if several operations are performed using the same +parameters. + +The meaning of the parameters passed to the callback will depend on the +algorithm and the specifiic implementation of the algorithm. Some might not +give any useful information at all during key or parameter generation. Others +might not even call the callback. + +The operation performed by key or parameter generation depends on the algorithm +used. In some cases (e.g. EC with a supplied named curve) the "generation" +option merely sets the appropriate fields in an EVP_PKEY structure. + +In OpenSSL an EVP_PKEY structure containing a private key also contains the +public key components and parameters (if any). An OpenSSL private key is +equivalent to what some libraries call a "key pair". A private key can be used +in functions which require the use of a public key or parameters. + +=head1 RETURN VALUES + +EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and +EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLES + +Generate a 2048 bit RSA key: + + #include + #include + + EVP_PKEY_CTX *ctx; + EVP_PKEY *pkey = NULL; + ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_keygen_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) + /* Error */ + + /* Generate key */ + if (EVP_PKEY_keygen(ctx, &pkey) <= 0) + /* Error */ + +Generate a key from a set of parameters: + + #include + #include + + EVP_PKEY_CTX *ctx; + EVP_PKEY *pkey = NULL, *param; + /* Assumed param is set up already */ + ctx = EVP_PKEY_CTX_new(param); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_keygen_init(ctx) <= 0) + /* Error */ + + /* Generate key */ + if (EVP_PKEY_keygen(ctx, &pkey) <= 0) + /* Error */ + +Example of generation callback for OpenSSL public key implementations: + + /* Application data is a BIO to output status to */ + + EVP_PKEY_CTX_set_app_data(ctx, status_bio); + + static int genpkey_cb(EVP_PKEY_CTX *ctx) + { + char c='*'; + BIO *b = EVP_PKEY_CTX_get_app_data(ctx); + int p; + p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); + if (p == 0) c='.'; + if (p == 1) c='+'; + if (p == 2) c='*'; + if (p == 3) c='\n'; + BIO_write(b,&c,1); + (void)BIO_flush(b); + return 1; + } + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod b/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod new file mode 100644 index 0000000000..ce9d70d7a7 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public key algorithm printing routines. + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx); + int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx); + int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx); + +=head1 DESCRIPTION + +The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and +EVP_PKEY_print_params() print out the public, private or parameter components +of key B respectively. The key is sent to BIO B in human readable +form. The parameter B indicated how far the printout should be indented. + +The B parameter allows the print output to be finely tuned by using +ASN1 printing options. If B is set to NULL then default values will +be used. + +=head1 NOTES + +Currently no public key algorithms include any options in the B parameter +parameter. + +If the key does not include all the components indicated by the function then +only those contained in the key will be printed. For example passing a public +key to EVP_PKEY_print_private() will only print the public components. + +=head1 RETURN VALUES + +These functions all return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 SEE ALSO + +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_sign.pod b/src/lib/libcrypto/doc/EVP_PKEY_sign.pod new file mode 100644 index 0000000000..2fb52c3486 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_sign.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, + unsigned char *sig, size_t *siglen, + const unsigned char *tbs, size_t tbslen); + +=head1 DESCRIPTION + +The EVP_PKEY_sign_init() function initializes a public key algorithm +context using key B for a signing operation. + +The EVP_PKEY_sign() function performs a public key signing operation +using B. The data to be signed is specified using the B and +B parameters. If B is B then the maximum size of the output +buffer is written to the B parameter. If B is not B then +before the call the B parameter should contain the length of the +B buffer, if the call is successful the signature is written to +B and the amount of data written to B. + +=head1 NOTES + +After the call to EVP_PKEY_sign_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_sign() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Sign data using RSA with PKCS#1 padding and SHA256 digest: + + #include + #include + + EVP_PKEY_CTX *ctx; + unsigned char *md, *sig; + size_t mdlen, siglen; + EVP_PKEY *signing_key; + /* NB: assumes signing_key, md and mdlen are already set up + * and that signing_key is an RSA private key + */ + ctx = EVP_PKEY_CTX_new(signing_key); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_sign_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) + /* Error */ + + sig = OPENSSL_malloc(siglen); + + if (!sig) + /* malloc failure */ + + if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) + /* Error */ + + /* Signature is siglen bytes written to buffer sig */ + + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_verify.pod b/src/lib/libcrypto/doc/EVP_PKEY_verify.pod new file mode 100644 index 0000000000..10633da3f2 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_PKEY_verify.pod @@ -0,0 +1,91 @@ +=pod + +=head1 NAME + +EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, + const unsigned char *sig, size_t siglen, + const unsigned char *tbs, size_t tbslen); + +=head1 DESCRIPTION + +The EVP_PKEY_verify_init() function initializes a public key algorithm +context using key B for a signature verification operation. + +The EVP_PKEY_verify() function performs a public key verification operation +using B. The signature is specified using the B and +B parameters. The verified data (i.e. the data believed originally +signed) is specified using the B and B parameters. + +=head1 NOTES + +After the call to EVP_PKEY_verify_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_verify() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was +successful and 0 if it failed. Unlike other functions the return value 0 from +EVP_PKEY_verify() only indicates that the signature did not not verify +successfully (that is tbs did not match the original data or the signature was +of invalid form) it is not an indication of a more serious error. + +A negative value indicates an error other that signature verification failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLE + +Verify signature using PKCS#1 and SHA256 digest: + + #include + #include + + EVP_PKEY_CTX *ctx; + unsigned char *md, *sig; + size_t mdlen, siglen; + EVP_PKEY *verify_key; + /* NB: assumes verify_key, sig, siglen md and mdlen are already set up + * and that verify_key is an RSA public key + */ + ctx = EVP_PKEY_CTX_new(verify_key); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_verify_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) + /* Error */ + + /* Perform operation */ + ret = EVP_PKEY_verify(ctx, md, mdlen, sig, siglen); + + /* ret == 1 indicates success, 0 verify failure and < 0 for some + * other error. + */ + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/EVP_SignInit.pod b/src/lib/libcrypto/doc/EVP_SignInit.pod index b6e62ce7f6..620a623ab6 100644 --- a/src/lib/libcrypto/doc/EVP_SignInit.pod +++ b/src/lib/libcrypto/doc/EVP_SignInit.pod @@ -77,6 +77,15 @@ will occur. Older versions of this documentation wrongly stated that calls to EVP_SignUpdate() could not be made after calling EVP_SignFinal(). +Since the private key is passed in the call to EVP_SignFinal() any error +relating to the private key (for example an unsuitable key and digest +combination) will not be indicated until after potentially large amounts of +data have been passed through EVP_SignUpdate(). + +It is not possible to change the signing parameters using these function. + +The previous two bugs are fixed in the newer EVP_SignDigest*() function. + =head1 SEE ALSO L, diff --git a/src/lib/libcrypto/doc/EVP_VerifyInit.pod b/src/lib/libcrypto/doc/EVP_VerifyInit.pod index b6afaedee5..9097f09410 100644 --- a/src/lib/libcrypto/doc/EVP_VerifyInit.pod +++ b/src/lib/libcrypto/doc/EVP_VerifyInit.pod @@ -67,6 +67,15 @@ will occur. Older versions of this documentation wrongly stated that calls to EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal(). +Since the public key is passed in the call to EVP_SignFinal() any error +relating to the private key (for example an unsuitable key and digest +combination) will not be indicated until after potentially large amounts of +data have been passed through EVP_SignUpdate(). + +It is not possible to change the signing parameters using these function. + +The previous two bugs are fixed in the newer EVP_VerifyDigest*() function. + =head1 SEE ALSO L, diff --git a/src/lib/libcrypto/doc/OBJ_nid2obj.pod b/src/lib/libcrypto/doc/OBJ_nid2obj.pod index 7dcc07923f..1e45dd40f6 100644 --- a/src/lib/libcrypto/doc/OBJ_nid2obj.pod +++ b/src/lib/libcrypto/doc/OBJ_nid2obj.pod @@ -8,6 +8,8 @@ functions =head1 SYNOPSIS + #include + ASN1_OBJECT * OBJ_nid2obj(int n); const char * OBJ_nid2ln(int n); const char * OBJ_nid2sn(int n); diff --git a/src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod b/src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod new file mode 100644 index 0000000000..e070c45c2e --- /dev/null +++ b/src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + + PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format. + +=head1 SYNOPSIS + + #include + #include + + int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); + +=head1 DESCRIPTION + +PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format. + +It is otherwise identical to the function SMIME_write_CMS(). + +=head1 NOTES + +This function is effectively a version of the PEM_write_bio_CMS() supporting +streaming. + +=head1 RETURN VALUES + +PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L, L, +L, L +L, +L, +L + +=head1 HISTORY + +PEM_write_bio_CMS_stream() was added to OpenSSL 1.0.0 + +=cut diff --git a/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod b/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod new file mode 100644 index 0000000000..16fc9b6845 --- /dev/null +++ b/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format. + +=head1 SYNOPSIS + + #include + #include + + int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); + +=head1 DESCRIPTION + +PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format. + +It is otherwise identical to the function SMIME_write_PKCS7(). + +=head1 NOTES + +This function is effectively a version of the PEM_write_bio_PKCS7() supporting +streaming. + +=head1 RETURN VALUES + +PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L, L, +L, L +L, +L, +L + +=head1 HISTORY + +PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0 + +=cut diff --git a/src/lib/libcrypto/doc/PKCS12_parse.pod b/src/lib/libcrypto/doc/PKCS12_parse.pod index 51344f883a..c54cf2ad61 100644 --- a/src/lib/libcrypto/doc/PKCS12_parse.pod +++ b/src/lib/libcrypto/doc/PKCS12_parse.pod @@ -20,24 +20,31 @@ certificate to B<*cert> and any additional certificates to B<*ca>. =head1 NOTES -The parameters B and B cannot be B. B can be -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 a new STACK will be allocated. +The parameters B and B cannot be B. B can be 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 a new STACK will be allocated. -The B and B attributes (if present) on each certificate -will be stored in the B and B attributes of the B structure. +The B and B attributes (if present) on each +certificate will be stored in the B and B attributes of the +B structure. + +=head1 RETURN VALUES + +PKCS12_parse() returns 1 for success and zero if an error occurred. + +The error can be obtained from L =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 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 and B attributes are currently stored in certificates. -Other attributes are discarded. +Only B and B attributes are currently stored in +certificates. Other attributes are discarded. -Attributes currently cannot be store in the private key B structure. +Attributes currently cannot be stored in the private key B structure. =head1 SEE ALSO diff --git a/src/lib/libcrypto/doc/PKCS7_decrypt.pod b/src/lib/libcrypto/doc/PKCS7_decrypt.pod index b0ca067b89..325699d0b6 100644 --- a/src/lib/libcrypto/doc/PKCS7_decrypt.pod +++ b/src/lib/libcrypto/doc/PKCS7_decrypt.pod @@ -6,7 +6,9 @@ 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); + #include + + int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags); =head1 DESCRIPTION diff --git a/src/lib/libcrypto/doc/PKCS7_encrypt.pod b/src/lib/libcrypto/doc/PKCS7_encrypt.pod index 1a507b22a2..2cd925a7e0 100644 --- a/src/lib/libcrypto/doc/PKCS7_encrypt.pod +++ b/src/lib/libcrypto/doc/PKCS7_encrypt.pod @@ -6,7 +6,9 @@ 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); + #include + + PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags); =head1 DESCRIPTION @@ -16,43 +18,55 @@ B is the symmetric cipher to use. B 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. +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. +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. +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 parameter must support ASN1 encoding of its -parameters. +The algorithm passed in the B parameter must support ASN1 encoding of +its parameters. -Many browsers implement a "sign and encrypt" option which is simply an S/MIME +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 parameter. -If the B flag is set MIME headers for type B are prepended -to the data. +If the B flag is set MIME headers for type B are +prepended to the data. -Normally the supplied content is translated into MIME canonical format (as required -by the S/MIME specifications) if B 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 is set then B is ignored. +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B 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 is set then +B is ignored. -=head1 RETURN VALUES +If the B flag is set a partial B structure is output +suitable for streaming I/O: no data is read from the BIO B. -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 NOTES -=head1 BUGS +If the flag B is set the returned B structure is B +complete and outputting its contents via a function that does not +properly finalize the B structure will give unpredictable +results. -The lack of single pass processing and need to hold all data in memory as -mentioned in PKCS7_sign() also applies to PKCS7_verify(). +Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), +PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B directly using +BIO_new_PKCS7(). + +=head1 RETURN VALUES + +PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred. +The error can be obtained from ERR_get_error(3). =head1 SEE ALSO @@ -61,5 +75,6 @@ L, L =head1 HISTORY PKCS7_decrypt() was added to OpenSSL 0.9.5 +The B flag was first supported in OpenSSL 1.0.0. =cut diff --git a/src/lib/libcrypto/doc/PKCS7_sign.pod b/src/lib/libcrypto/doc/PKCS7_sign.pod index ffd0c734b0..64a35144f8 100644 --- a/src/lib/libcrypto/doc/PKCS7_sign.pod +++ b/src/lib/libcrypto/doc/PKCS7_sign.pod @@ -6,14 +6,16 @@ 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); + #include + + 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 -is the certificate to sign with, B is the corresponsding private key. -B is an optional additional set of certificates to include in the -PKCS#7 structure (for example any intermediate CAs in the chain). +PKCS7_sign() creates and returns a PKCS#7 signedData structure. B is +the certificate to sign with, B is the corresponsding private key. +B 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. @@ -21,72 +23,83 @@ B is an optional set of flags. =head1 NOTES -Any of the following flags (ored together) can be passed in the B parameter. +Any of the following flags (ored together) can be passed in the B +parameter. Many S/MIME clients expect the signed content to include valid MIME headers. If the B flag is set MIME headers for type B are prepended to the data. If B 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 -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 -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. +PKCS7 structure, the signer's certificate must still be supplied in the +B 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 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 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 is set then no +authenticatedAttributes will be used. If B is set then just +the SMIMECapabilities are omitted. -Normally the supplied content is translated into MIME canonical format (as required -by the S/MIME specifications) if B 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 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. -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 is set then no authenticatedAttributes -will be used. If B is set then just the SMIMECapabilities are -omitted. +If the flags B is set then the returned B structure is +just initialized ready to perform the signing operation. The signing is however +B performed and the data to be signed is not read from the B +parameter. Signing is deferred until after the data has been written. In this +way data can be signed in a single pass. -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 B flag is set a partial B structure is output to +which additional signers and capabilities can be added before finalization. -If the flags B is set then the returned B structure -is just initialized ready to perform the signing operation. The signing -is however B performed and the data to be signed is not read from -the B 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 B also be set. =head1 NOTES -Currently the flag B is only supported for detached -data. If this flag is set the returned B structure is B -complete and outputting its contents via a function that does not -properly finalize the B structure will give unpredictable -results. +If the flag B is set the returned B structure is B +complete and outputting its contents via a function that does not properly +finalize the B structure will give unpredictable results. -At present only the SMIME_write_PKCS7() function properly finalizes the -structure. +Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), +PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B directly using +BIO_new_PKCS7(). -=head1 BUGS +If a signer is specified it will use the default digest for the signing +algorithm. This is B for both RSA and DSA keys. + +In OpenSSL 1.0.0 the B, B and B parameters can all be +B if the B flag is set. One or more signers can be added +using the function B. B must also be +called to finalize the structure if streaming is not enabled. Alternative +signing digests can also be specified using this method. -PKCS7_sign() is somewhat limited. It does not support multiple signers, some -advanced attributes such as counter signatures are not supported. +In OpenSSL 1.0.0 if B and B are NULL then a certificates only +PKCS#7 structure is output. -The SHA1 digest algorithm is currently always used. +In versions of OpenSSL before 1.0.0 the B and B parameters must +B be NULL. -When the signed data is not detached it will be stored in memory within the -B 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 BUGS +Some advanced attributes such as counter signatures are not supported. =head1 RETURN VALUES -PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred. -The error can be obtained from ERR_get_error(3). +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 @@ -96,6 +109,8 @@ L, L PKCS7_sign() was added to OpenSSL 0.9.5 -The B flag was added in OpenSSL 0.9.8 +The B flag was added in OpenSSL 1.0.0 + +The B flag was added in OpenSSL 1.0.0 =cut diff --git a/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod b/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod new file mode 100644 index 0000000000..ebec4d57de --- /dev/null +++ b/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +PKCS7_sign_add_signer - add a signer PKCS7 signed data structure. + +=head1 SYNOPSIS + + #include + + PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags); + + +=head1 DESCRIPTION + +PKCS7_sign_add_signer() adds a signer with certificate B and private +key B using message digest B to a PKCS7 signed data structure +B. + +The PKCS7 structure should be obtained from an initial call to PKCS7_sign() +with the flag B set or in the case or re-signing a valid PKCS7 +signed data structure. + +If the B parameter is B then the default digest for the public +key algorithm will be used. + +Unless the B flag is set the returned PKCS7 structure +is not complete and must be finalized either by streaming (if applicable) or +a call to PKCS7_final(). + + +=head1 NOTES + +The main purpose of this function is to provide finer control over a PKCS#7 +signed data structure where the simpler PKCS7_sign() function defaults are +not appropriate. For example if multiple signers or non default digest +algorithms are needed. + +Any of the following flags (ored together) can be passed in the B +parameter. + +If B is set then an attempt is made to copy the content +digest value from the PKCS7 struture: to add a signer to an existing structure. +An error occurs if a matching digest value cannot be found to copy. The +returned PKCS7 structure will be valid and finalized when this flag is set. + +If B is set in addition to B then the +B structure will not be finalized so additional attributes +can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is +needed to finalize it. + +If B 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 parameter though. This can reduce the size of the signature if the +signers certificate can be obtained by other means: for example a previously +signed message. + +The signedData structure includes several PKCS#7 autenticatedAttributes +including the signing time, the PKCS#7 content type and the supported list of +ciphers in an SMIMECapabilities attribute. If B is set then no +authenticatedAttributes will be used. If B is set then just +the SMIMECapabilities are omitted. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of +these algorithms is disabled then it will not be included. + + +PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO +structure just added, this can be used to set additional attributes +before it is finalized. + +=head1 RETURN VALUES + +PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO +structure just added or NULL if an error occurs. + +=head1 SEE ALSO + +L, L, +L, + +=head1 HISTORY + +PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0 + +=cut diff --git a/src/lib/libcrypto/doc/PKCS7_verify.pod b/src/lib/libcrypto/doc/PKCS7_verify.pod index 3490b5dc82..7c10a4cc3c 100644 --- a/src/lib/libcrypto/doc/PKCS7_verify.pod +++ b/src/lib/libcrypto/doc/PKCS7_verify.pod @@ -6,9 +6,11 @@ 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); + #include -STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); + 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 diff --git a/src/lib/libcrypto/doc/SMIME_read_CMS.pod b/src/lib/libcrypto/doc/SMIME_read_CMS.pod new file mode 100644 index 0000000000..acc5524c14 --- /dev/null +++ b/src/lib/libcrypto/doc/SMIME_read_CMS.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + + SMIME_read_CMS - parse S/MIME message. + +=head1 SYNOPSIS + + #include + + CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont); + +=head1 DESCRIPTION + +SMIME_read_CMS() parses a message in S/MIME format. + +B is a BIO to read the message from. + +If cleartext signing is used then the content is saved in a memory bio which is +written to B<*bcont>, otherwise B<*bcont> is set to NULL. + +The parsed CMS_ContentInfo structure is returned or NULL if an +error occurred. + +=head1 NOTES + +If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can +then be passed to CMS_verify() with the B flag set. + +Otherwise the type of the returned structure can be determined +using CMS_get0_type(). + +To support future functionality if B is not NULL B<*bcont> should be +initialized to NULL. For example: + + BIO *cont = NULL; + CMS_ContentInfo *cms; + + cms = SMIME_read_CMS(in, &cont); + +=head1 BUGS + +The MIME parser used by SMIME_read_CMS() is somewhat primitive. While it will +handle most S/MIME messages more complex compound formats may not work. + +The parser assumes that the CMS_ContentInfo structure is always base64 encoded +and will not handle the case where it is in binary format or uses quoted +printable format. + +The use of a memory BIO to hold the signed content limits the size of message +which can be processed due to memory restraints: a streaming single pass option +should be available. + +=head1 RETURN VALUES + +SMIME_read_CMS() returns a valid B structure or B +if an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L +L, L, +L, L +L + +=head1 HISTORY + +SMIME_read_CMS() was added to OpenSSL 0.9.8 + +=cut diff --git a/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod b/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod index ffafa37887..9d46715941 100644 --- a/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod +++ b/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod @@ -6,7 +6,9 @@ SMIME_read_PKCS7 - parse S/MIME message. =head1 SYNOPSIS -PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont); + #include + + PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont); =head1 DESCRIPTION diff --git a/src/lib/libcrypto/doc/SMIME_write_CMS.pod b/src/lib/libcrypto/doc/SMIME_write_CMS.pod new file mode 100644 index 0000000000..04bedfb429 --- /dev/null +++ b/src/lib/libcrypto/doc/SMIME_write_CMS.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + + SMIME_write_CMS - convert CMS structure to S/MIME format. + +=head1 SYNOPSIS + + #include + + int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); + +=head1 DESCRIPTION + +SMIME_write_CMS() adds the appropriate MIME headers to a CMS +structure to produce an S/MIME message. + +B is the BIO to write the data to. B is the appropriate +B structure. If streaming is enabled then the content must be +supplied in the B argument. B is an optional set of flags. + +=head1 NOTES + +The following flags can be passed in the B parameter. + +If B is set then cleartext signing will be used, this option only +makes sense for SignedData where B is also set when CMS_sign() is +called. + +If the B flag is set MIME headers for type B are added to +the content, this only makes sense if B is also set. + +If the B flag is set streaming is performed. This flag should only +be set if B was also set in the previous call to a CMS_ContentInfo +creation function. + +If cleartext signing is being used and B not set then the data must +be read twice: once to compute the signature in CMS_sign() and once to output +the S/MIME message. + +If streaming is performed the content is output in BER format using indefinite +length constructed encoding except in the case of signed data with detached +content where the content is absent and DER format is used. + +=head1 BUGS + +SMIME_write_CMS() always base64 encodes CMS structures, there should be an +option to disable this. + +=head1 RETURN VALUES + +SMIME_write_CMS() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L, L, +L, L +L + +=head1 HISTORY + +SMIME_write_CMS() was added to OpenSSL 0.9.8 + +=cut diff --git a/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod b/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod index 61945b3887..ca6bd02763 100644 --- a/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod +++ b/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod @@ -6,17 +6,18 @@ 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); + #include + + 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 is the BIO to write the data to. B is the appropriate -B structure. If cleartext signing (B) is -being used then the signed data must be supplied in the B -argument. B is an optional set of flags. +B is the BIO to write the data to. B is the appropriate B +structure. If streaming is enabled then the content must be supplied in the +B argument. B is an optional set of flags. =head1 NOTES @@ -30,15 +31,18 @@ If the B flag is set MIME headers for type B are added to the content, this only makes sense if B is also set. -If the B flag is set the signed data is finalized -and output along with the content. This flag should only be set -if B is also set and the previous call to PKCS7_sign() -also set these flags. +If the B flag is set streaming is performed. This flag should +only be set if B was also set in the previous call to +PKCS7_sign() or B. -If cleartext signing is being used and B not set then +If cleartext signing is being used and B not set then the data must be read twice: once to compute the signature in PKCS7_sign() and once to output the S/MIME message. +If streaming is performed the content is output in BER format using indefinite +length constructuted encoding except in the case of signed data with detached +content where the content is absent and DER format is used. + =head1 BUGS SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there diff --git a/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod b/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod index 11b35f6fd3..41902c0d45 100644 --- a/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod +++ b/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod @@ -9,15 +9,17 @@ 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); + #include -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); + ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne); + ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne); -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); + 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 diff --git a/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod b/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod index e2ab4b0d2b..1afd008cb3 100644 --- a/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod +++ b/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod @@ -7,15 +7,17 @@ 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); + #include -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_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_NID(X509_NAME *name, int nid, int type, 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(X509_NAME *name,X509_NAME_ENTRY *ne, 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); -X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); + 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 diff --git a/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod b/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod index 333323d734..3b1f9ff43b 100644 --- a/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod +++ b/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod @@ -8,14 +8,16 @@ 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); + #include -int X509_NAME_entry_count(X509_NAME *name); -X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc); + 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_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); + 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 diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod new file mode 100644 index 0000000000..a883f6c097 --- /dev/null +++ b/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod @@ -0,0 +1,303 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, X509_STORE_CTX_get_error_depth, X509_STORE_CTX_get_current_cert, X509_STORE_CTX_get1_chain, X509_verify_cert_error_string - get or set certificate verification status information + +=head1 SYNOPSIS + + #include + #include + + int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s); + int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); + X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); + + STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); + + const char *X509_verify_cert_error_string(long n); + +=head1 DESCRIPTION + +These functions are typically called after X509_verify_cert() has indicated +an error or in a verification callback to determine the nature of an error. + +X509_STORE_CTX_get_error() returns the error code of B, see +the B section for a full description of all error codes. + +X509_STORE_CTX_set_error() sets the error code of B to B. For example +it might be used in a verification callback to set an error based on additional +checks. + +X509_STORE_CTX_get_error_depth() returns the B of the error. This is a +non-negative integer representing where in the certificate chain the error +occurred. If it is zero it occured in the end entity certificate, one if +it is the certificate which signed the end entity certificate and so on. + +X509_STORE_CTX_get_current_cert() returns the certificate in B which +caused the error or B if no certificate is relevant. + +X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous +call to X509_verify_cert() is successful. If the call to X509_verify_cert() +is B successful the returned chain may be incomplete or invalid. The +returned chain persists after the B structure is freed, when it is +no longer needed it should be free up using: + + sk_X509_pop_free(chain, X509_free); + +X509_verify_cert_error_string() returns a human readable error string for +verification error B. + +=head1 RETURN VALUES + +X509_STORE_CTX_get_error() returns B or an error code. + +X509_STORE_CTX_get_error_depth() returns a non-negative error depth. + +X509_STORE_CTX_get_current_cert() returns the cerificate which caused the +error or B if no certificate is relevant to the error. + +X509_verify_cert_error_string() returns a human readable error string for +verification error B. + +=head1 ERROR CODES + +A list of error codes and messages is shown below. Some of the +error codes are defined but currently never returned: these are described as +"unused". + +=over 4 + +=item B + +the operation was successful. + +=item B + +the issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. + +=item B + +the CRL of a certificate could not be found. + +=item B + +the certificate signature could not be decrypted. This means that the actual +signature value could not be determined rather than it not matching the +expected value, this is only meaningful for RSA keys. + +=item B + +the CRL signature could not be decrypted: this means that the actual signature +value could not be determined rather than it not matching the expected value. +Unused. + +=item B + +the public key in the certificate SubjectPublicKeyInfo could not be read. + +=item B + +the signature of the certificate is invalid. + +=item B + +the signature of the certificate is invalid. + +=item B + +the certificate is not yet valid: the notBefore date is after the current time. + +=item B + +the certificate has expired: that is the notAfter date is before the current time. + +=item B + +the CRL is not yet valid. + +=item B + +the CRL has expired. + +=item B + +the certificate notBefore field contains an invalid time. + +=item B + +the certificate notAfter field contains an invalid time. + +=item B + +the CRL lastUpdate field contains an invalid time. + +=item B + +the CRL nextUpdate field contains an invalid time. + +=item B + +an error occurred trying to allocate memory. This should never happen. + +=item B + +the passed certificate is self signed and the same certificate cannot be found +in the list of trusted certificates. + +=item B + +the certificate chain could be built up using the untrusted certificates but +the root could not be found locally. + +=item B + +the issuer certificate of a locally looked up certificate could not be found. +This normally means the list of trusted certificates is not complete. + +=item B + +no signatures could be verified because the chain contains only one certificate +and it is not self signed. + +=item B + +the certificate chain length is greater than the supplied maximum depth. Unused. + +=item B + +the certificate has been revoked. + +=item B + +a CA certificate is invalid. Either it is not a CA or its extensions are not +consistent with the supplied purpose. + +=item B + +the basicConstraints pathlength parameter has been exceeded. + +=item B + +the supplied certificate cannot be used for the specified purpose. + +=item B + +the root CA is not marked as trusted for the specified purpose. + +=item B + +the root CA is marked to reject the specified purpose. + +=item B + +the current candidate issuer certificate was rejected because its subject name +did not match the issuer name of the current certificate. This is only set +if issuer check debugging is enabled it is used for status notification and +is B in itself an error. + +=item B + +the current candidate issuer certificate was rejected because its subject key +identifier was present and did not match the authority key identifier current +certificate. This is only set if issuer check debugging is enabled it is used +for status notification and is B in itself an error. + +=item B + +the current candidate issuer certificate was rejected because its issuer name +and serial number was present and did not match the authority key identifier of +the current certificate. This is only set if issuer check debugging is enabled +it is used for status notification and is B in itself an error. + +=item B + +the current candidate issuer certificate was rejected because its keyUsage +extension does not permit certificate signing. This is only set if issuer check +debugging is enabled it is used for status notification and is B in itself +an error. + +=item B + +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. + + +=item B + +A certificate policies extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. This error only +occurs if policy processing is enabled. + +=item B + +The verification flags were set to require and explicit policy but none was +present. + +=item B + +The only CRLs that could be found did not match the scope of the certificate. + +=item B + +Some feature of a certificate extension is not supported. Unused. + +=item B + +A name constraint violation occured in the permitted subtrees. + +=item B + +A name constraint violation occured in the excluded subtrees. + +=item B + +A certificate name constraints extension included a minimum or maximum field: +this is not supported. + +=item B + +An unsupported name constraint type was encountered. OpenSSL currently only +supports directory name, DNS name, email and URI types. + +=item B + +The format of the name constraint is not recognised: for example an email +address format of a form not mentioned in RFC3280. This could be caused by +a garbage extension or some new feature not currently supported. + +=item B + +An error occured when attempting to verify the CRL path. This error can only +happen if extended CRL checking is enabled. + +=item B + +an application specific error. This will never be returned unless explicitly +set by an application. + +=head1 NOTES + +The above functions should be used instead of directly referencing the fields +in the B structure. + +In versions of OpenSSL before 1.0 the current certificate returned by +X509_STORE_CTX_get_current_cert() was never B. Applications should +check the return value before printing out any debugging information relating +to the current certificate. + +If an unrecognised error code is passed to X509_verify_cert_error_string() the +numerical value of the unknown code is returned in a static buffer. This is not +thread safe but will never happen unless an invalid code is passed. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod new file mode 100644 index 0000000000..8d6b9dda47 --- /dev/null +++ b/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data - add application specific data to X509_STORE_CTX structures + +=head1 SYNOPSIS + + #include + + int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); + + char *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); + +=head1 DESCRIPTION + +These functions handle application specific data in X509_STORE_CTX 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. + +=head1 NOTES + +This mechanism is used internally by the B library to store the B +structure associated with a verification operation in an B +structure. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +X509_STORE_CTX_get_ex_new_index(), X509_STORE_CTX_set_ex_data() and +X509_STORE_CTX_get_ex_data() are available since OpenSSL 0.9.5. + +=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod new file mode 100644 index 0000000000..b17888f149 --- /dev/null +++ b/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default - X509_STORE_CTX initialisation + +=head1 SYNOPSIS + + #include + + X509_STORE_CTX *X509_STORE_CTX_new(void); + void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); + void X509_STORE_CTX_free(X509_STORE_CTX *ctx); + + int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, + X509 *x509, STACK_OF(X509) *chain); + + void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); + + void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x); + void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk); + void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); + + X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); + int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); + +=head1 DESCRIPTION + +These functions initialise an B structure for subsequent use +by X509_verify_cert(). + +X509_STORE_CTX_new() returns a newly initialised B structure. + +X509_STORE_CTX_cleanup() internally cleans up an B structure. +The context can then be reused with an new call to X509_STORE_CTX_init(). + +X509_STORE_CTX_free() completely frees up B. After this call B +is no longer valid. + +X509_STORE_CTX_init() sets up B for a subsequent verification operation. +The trusted certificate store is set to B, the end entity certificate +to be verified is set to B and a set of additional certificates (which +will be untrusted but may be used to build the chain) in B. Any or +all of the B, B and B parameters can be B. + +X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B +to B. This is an alternative way of specifying trusted certificates +instead of using an B. + +X509_STORE_CTX_set_cert() sets the certificate to be vertified in B to +B. + +X509_STORE_CTX_set_chain() sets the additional certificate chain used by B +to B. + +X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate +verification to B. These CRLs will only be used if CRL verification is +enabled in the associated B structure. This might be +used where additional "useful" CRLs are supplied as part of a protocol, +for example in a PKCS#7 structure. + +X509_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an intenal pointer +to the verification parameters associated with B. + +X509_STORE_CTX_set0_param() sets the intenal verification parameter pointer +to B. After this call B should not be used. + +X509_STORE_CTX_set_default() looks up and sets the default verification +method to B. This uses the function X509_VERIFY_PARAM_lookup() to +find an appropriate set of parameters from B. + +=head1 NOTES + +The certificates and CRLs in a store are used internally and should B +be freed up until after the associated B is freed. Legacy +applications might implicitly use an B like this: + + X509_STORE_CTX ctx; + X509_STORE_CTX_init(&ctx, store, cert, chain); + +this is B recommended in new applications they should instead do: + + X509_STORE_CTX *ctx; + ctx = X509_STORE_CTX_new(); + if (ctx == NULL) + /* Bad error */ + X509_STORE_CTX_init(ctx, store, cert, chain); + +=head1 BUGS + +The certificates and CRLs in a context are used internally and should B +be freed up until after the associated B is freed. Copies +should be made or reference counts increased instead. + +=head1 RETURN VALUES + +X509_STORE_CTX_new() returns an newly allocates context or B is an +error occurred. + +X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred. + +X509_STORE_CTX_get0_param() returns a pointer to an B +structure or B if an error occurred. + +X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), X509_STORE_CTX_trusted_stack(), +X509_STORE_CTX_set_cert(), X509_STORE_CTX_set_chain(), +X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return +values. + +X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. + +=head1 SEE ALSO + +L +L + +=head1 HISTORY + +X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 + +=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod new file mode 100644 index 0000000000..b9787a6ca6 --- /dev/null +++ b/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod @@ -0,0 +1,161 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_set_verify_cb - set verification callback + +=head1 SYNOPSIS + + #include + + void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, + int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + +=head1 DESCRIPTION + +X509_STORE_CTX_set_verify_cb() sets the verification callback of B to +B overwriting any existing callback. + +The verification callback can be used to customise the operation of certificate +verification, either by overriding error conditions or logging errors for +debugging purposes. + +However a verification callback is B essential and the default operation +is often sufficient. + +The B parameter to the callback indicates the value the callback should +return to retain the default behaviour. If it is zero then and error condition +is indicated. If it is 1 then no error occurred. If the flag +B is set then B is set to 2 to indicate the +policy checking is complete. + +The B parameter to the callback is the B structure that +is performing the verification operation. A callback can examine this +structure and receive additional information about the error, for example +by calling X509_STORE_CTX_get_current_cert(). Additional application data can +be passed to the callback via the B mechanism. + +=head1 WARNING + +In general a verification callback should B unconditionally return 1 in +all circumstances because this will allow verification to succeed no matter +what the error. This effectively removes all security from the application +because B certificate (including untrusted generated ones) will be +accepted. + +=head1 NOTES + +The verification callback can be set and inherited from the parent structure +performing the operation. In some cases (such as S/MIME verification) the +B structure is created and destroyed internally and the +only way to set a custom verification callback is by inheriting it from the +associated B. + +=head1 RETURN VALUES + +X509_STORE_CTX_set_verify_cb() does not return a value. + +=head1 EXAMPLES + +Default callback operation: + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + return ok; + } + +Simple example, suppose a certificate in the chain is expired and we wish +to continue after this error: + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + /* Tolerate certificate expiration */ + if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) + return 1; + /* Otherwise don't override */ + return ok; + } + +More complex example, we don't wish to continue after B certificate has +expired just one specific case: + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + int err = X509_STORE_CTX_get_error(ctx); + X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); + if (err == X509_V_ERR_CERT_HAS_EXPIRED) + { + if (check_is_acceptable_expired_cert(err_cert) + return 1; + } + return ok; + } + +Full featured logging callback. In this case the B is assumed to be +a global logging B, an alternative would to store a BIO in B using +B. + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + X509 *err_cert; + int err,depth; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + BIO_printf(bio_err,"depth=%d ",depth); + if (err_cert) + { + X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert), + 0, XN_FLAG_ONELINE); + BIO_puts(bio_err, "\n"); + } + else + BIO_puts(bio_err, "\n"); + if (!ok) + BIO_printf(bio_err,"verify error:num=%d:%s\n",err, + X509_verify_cert_error_string(err)); + switch (err) + { + case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: + BIO_puts(bio_err,"issuer= "); + X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert), + 0, XN_FLAG_ONELINE); + BIO_puts(bio_err, "\n"); + break; + case X509_V_ERR_CERT_NOT_YET_VALID: + case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: + BIO_printf(bio_err,"notBefore="); + ASN1_TIME_print(bio_err,X509_get_notBefore(err_cert)); + BIO_printf(bio_err,"\n"); + break; + case X509_V_ERR_CERT_HAS_EXPIRED: + case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: + BIO_printf(bio_err,"notAfter="); + ASN1_TIME_print(bio_err,X509_get_notAfter(err_cert)); + BIO_printf(bio_err,"\n"); + break; + case X509_V_ERR_NO_EXPLICIT_POLICY: + policies_print(bio_err, ctx); + break; + } + if (err == X509_V_OK && ok == 2) + /* print out policies */ + + BIO_printf(bio_err,"verify return:%d\n",ok); + return(ok); + } + +=head1 SEE ALSO + +L +L +L + +=head1 HISTORY + +X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and +OpenSSL. + +=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod b/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod new file mode 100644 index 0000000000..29e3bbe3bc --- /dev/null +++ b/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb - set verification callback + +=head1 SYNOPSIS + + #include + + void X509_STORE_set_verify_cb(X509_STORE *st, + int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + + void X509_STORE_set_verify_cb_func(X509_STORE *st, + int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + +=head1 DESCRIPTION + +X509_STORE_set_verify_cb() sets the verification callback of B to +B overwriting any existing callback. + +X509_STORE_set_verify_cb_func() also sets the verification callback but it +is implemented as a macro. + +=head1 NOTES + +The verification callback from an B is inherited by +the corresponding B structure when it is initialized. This can +be used to set the verification callback when the B is +otherwise inaccessible (for example during S/MIME verification). + +=head1 BUGS + +The macro version of this function was the only one available before +OpenSSL 1.0.0. + +=head1 RETURN VALUES + +X509_STORE_set_verify_cb() and X509_STORE_set_verify_cb_func() do not return +a value. + +=head1 SEE ALSO + +L +L + +=head1 HISTORY + +X509_STORE_set_verify_cb_func() is available in all versions of SSLeay and +OpenSSL. + +X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod b/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod new file mode 100644 index 0000000000..b68eece033 --- /dev/null +++ b/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod @@ -0,0 +1,171 @@ +=pod + +=head1 NAME + +X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 verification parameters + +=head1 SYNOPSIS + + #include + + int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); + int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, + unsigned long flags); + unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); + + int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); + int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); + + void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); + + int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, + ASN1_OBJECT *policy); + int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, + STACK_OF(ASN1_OBJECT) *policies); + + void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); + int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); + +=head1 DESCRIPTION + +These functions manipulate the B structure associated with +a certificate verification operation. + +The X509_VERIFY_PARAM_set_flags() function sets the flags in B by oring +it with B. See the B section for a complete +description of values the B parameter can take. + +X509_VERIFY_PARAM_get_flags() returns the flags in B. + +X509_VERIFY_PARAM_clear_flags() clears the flags B in B. + +X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B +to B. This determines the acceptable purpose of the certificate +chain, for example SSL client or SSL server. + +X509_VERIFY_PARAM_set_trust() sets the trust setting in B to +B. + +X509_VERIFY_PARAM_set_time() sets the verification time in B to +B. Normally the current time is used. + +X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled +by default) and adds B to the acceptable policy set. + +X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled +by default) and sets the acceptable policy set to B. Any existing +policy set is cleared. The B parameter can be B to clear +an existing policy set. + +X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B. +That is the maximum number of untrusted CA certificates that can appear in a +chain. + +=head1 RETURN VALUES + +X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), +X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), +X509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1 +for success and 0 for failure. + +X509_VERIFY_PARAM_get_flags() returns the current verification flags. + +X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return +values. + +X509_VERIFY_PARAM_get_depth() returns the current verification depth. + +=head1 VERIFICATION FLAGS + +The verification flags consists of zero or more of the following flags +ored together. + +B enables CRL checking for the certificate chain leaf +certificate. An error occurs if a suitable CRL cannot be found. + +B enables CRL checking for the entire certificate +chain. + +B disabled critical extension checking. By default +any unhandled critical extensions in certificates or (if checked) CRLs results +in a fatal error. If this flag is set unhandled critical extensions are +ignored. B setting this option for anything other than debugging +purposes can be a security risk. Finer control over which extensions are +supported can be performed in the verification callback. + +THe B flag disables workarounds for some broken +certificates and makes the verification strictly apply B rules. + +B enables proxy certificate verification. + +B enables certificate policy checking, by default +no policy checking is peformed. Additional information is sent to the +verification callback relating to policy checking. + +B, B and +B set the B, B and B flags respectively as defined in +B. Policy checking is automatically enabled if any of these flags +are set. + +If B is set and the policy checking is successful +a special status code is set to the verification callback. This permits it +to examine the valid policy tree and perform additional checks or simply +log it for debugging purposes. + +By default some addtional features such as indirect CRLs and CRLs signed by +different keys are disabled. If B is set +they are enabled. + +If B ise set delta CRLs (if present) are used to +determine certificate status. If not set deltas are ignored. + +B enables checking of the root CA self signed +cerificate signature. By default this check is disabled because it doesn't +add any additional security but in some cases applications might want to +check the signature anyway. A side effect of not checking the root CA +signature is that disabled or unsupported message digests on the root CA +are not treated as fatal errors. + +The B flag enables debugging of certificate +issuer checks. It is B needed unless you are logging certificate +verification. If this flag is set then additional status codes will be sent +to the verification callback and it B be prepared to handle such cases +without assuming they are hard errors. + +=head1 NOTES + +The above functions should be used to manipulate verification parameters +instead of legacy functions which work in specific structures such as +X509_STORE_CTX_set_flags(). + +=head1 BUGS + +Delta CRL checking is currently primitive. Only a single delta can be used and +(partly due to limitations of B) constructed CRLs are not +maintained. + +If CRLs checking is enable CRLs are expected to be available in the +corresponding B structure. No attempt is made to download +CRLs from the CRL distribution points extension. + +=head1 EXAMPLE + +Enable CRL checking when performing certificate verification during SSL +connections associated with an B structure B: + + X509_VERIFY_PARAM *param; + param = X509_VERIFY_PARAM_new(); + X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); + SSL_CTX_set1_param(ctx, param); + X509_VERIFY_PARAM_free(param); + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut diff --git a/src/lib/libcrypto/doc/X509_new.pod b/src/lib/libcrypto/doc/X509_new.pod index fd5fc65ce1..d38872335f 100644 --- a/src/lib/libcrypto/doc/X509_new.pod +++ b/src/lib/libcrypto/doc/X509_new.pod @@ -6,6 +6,8 @@ X509_new, X509_free - X509 certificate ASN1 allocation functions =head1 SYNOPSIS + #include + X509 *X509_new(void); void X509_free(X509 *a); diff --git a/src/lib/libcrypto/doc/X509_verify_cert.pod b/src/lib/libcrypto/doc/X509_verify_cert.pod new file mode 100644 index 0000000000..5253bdcd70 --- /dev/null +++ b/src/lib/libcrypto/doc/X509_verify_cert.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +X509_verify_cert - discover and verify X509 certificte chain + +=head1 SYNOPSIS + + #include + + int X509_verify_cert(X509_STORE_CTX *ctx); + +=head1 DESCRIPTION + +The X509_verify_cert() function attempts to discover and validate a +certificate chain based on parameters in B. A complete description of +the process is contained in the L manual page. + +=head1 RETURN VALUES + +If a complete chain can be built and validated this function returns 1, +otherwise it return zero, in exceptional circumstances it can also +return a negative code. + +If the function fails additional error information can be obtained by +examining B using, for example X509_STORE_CTX_get_error(). + +=head1 NOTES + +Applications rarely call this function directly but it is used by +OpenSSL internally for certificate validation, in both the S/MIME and +SSL/TLS code. + +The negative return value from X509_verify_cert() can only occur if no +certificate is set in B (due to a programming error) or if a retry +operation is requested during internal lookups (which never happens with +standard lookup methods). It is however recommended that application check +for <= 0 return value on error. + +=head1 BUGS + +This function uses the header B as opposed to most chain verification +functiosn which use B. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +X509_verify_cert() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod b/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod index 279b29c873..aa6078bcf6 100644 --- a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod +++ b/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod @@ -11,21 +11,21 @@ d2i_Netscape_RSA - RSA public and private key encoding functions. #include #include - RSA * d2i_RSAPublicKey(RSA **a, unsigned char **pp, long length); + RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length); int i2d_RSAPublicKey(RSA *a, unsigned char **pp); - RSA * d2i_RSA_PUBKEY(RSA **a, unsigned char **pp, long length); + RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length); int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); - RSA * d2i_RSAPrivateKey(RSA **a, unsigned char **pp, long length); + RSA * d2i_RSAPrivateKey(RSA **a, const 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)()); + RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); =head1 DESCRIPTION diff --git a/src/lib/libcrypto/doc/d2i_X509.pod b/src/lib/libcrypto/doc/d2i_X509.pod index 5bfa18afbb..298ec54a4c 100644 --- a/src/lib/libcrypto/doc/d2i_X509.pod +++ b/src/lib/libcrypto/doc/d2i_X509.pod @@ -15,8 +15,8 @@ i2d_X509_fp - X509 encode and decode functions 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); + int i2d_X509_bio(BIO *bp, X509 *x); + int i2d_X509_fp(FILE *fp, X509 *x); =head1 DESCRIPTION @@ -212,11 +212,11 @@ d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B structure or B if an error occurs. The error code that can be obtained by L. -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. +i2d_X509() returns the number of bytes successfully encoded or a negative +value if an error occurs. The error code can be obtained by +L. -i2d_X509_bio() and i2d_X509_fp() returns 1 for success and 0 if an error +i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error occurs The error code can be obtained by L. =head1 SEE ALSO diff --git a/src/lib/libcrypto/doc/d2i_X509_CRL.pod b/src/lib/libcrypto/doc/d2i_X509_CRL.pod index e7295a5d61..224f9e082b 100644 --- a/src/lib/libcrypto/doc/d2i_X509_CRL.pod +++ b/src/lib/libcrypto/doc/d2i_X509_CRL.pod @@ -15,8 +15,8 @@ i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions. 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); + int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x); + int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x); =head1 DESCRIPTION diff --git a/src/lib/libcrypto/doc/d2i_X509_REQ.pod b/src/lib/libcrypto/doc/d2i_X509_REQ.pod index ae32a3891d..91c0c1974b 100644 --- a/src/lib/libcrypto/doc/d2i_X509_REQ.pod +++ b/src/lib/libcrypto/doc/d2i_X509_REQ.pod @@ -15,8 +15,8 @@ i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions. 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); + int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x); + int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x); =head1 DESCRIPTION diff --git a/src/lib/libcrypto/doc/evp.pod b/src/lib/libcrypto/doc/evp.pod index b3ca14314f..9faa349243 100644 --- a/src/lib/libcrypto/doc/evp.pod +++ b/src/lib/libcrypto/doc/evp.pod @@ -22,14 +22,24 @@ digital signatures. Symmetric encryption is available with the BI<...> functions. The BI<...> functions provide message digests. +The BI<...> functions provide a high level interface to +asymmetric algorithms. + 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. +All the symmetric algorithms (ciphers), digests and asymmetric algorithms +(public key algorithms) 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. + +Although low level algorithm specific functions exist for many algorithms +their use is discouraged. They cannot be used with an ENGINE and ENGINE +versions of new algorithms cannot be accessed using the low level functions. +Also makes code harder to adapt to new algorithms and some options are not +cleanly supported at the low level and some operations are more efficient +using the high level interface. =head1 SEE ALSO diff --git a/src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod b/src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod new file mode 100644 index 0000000000..558bdd0812 --- /dev/null +++ b/src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + + i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format. + +=head1 SYNOPSIS + + #include + + int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); + +=head1 DESCRIPTION + +i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format. + +It is otherwise identical to the function SMIME_write_CMS(). + +=head1 NOTES + +This function is effectively a version of the i2d_CMS_bio() supporting +streaming. + +=head1 BUGS + +The prefix "i2d" is arguably wrong because the function outputs BER format. + +=head1 RETURN VALUES + +i2d_CMS_bio_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L, L, +L, L +L, +L, +L + +=head1 HISTORY + +i2d_CMS_bio_stream() was added to OpenSSL 1.0.0 + +=cut diff --git a/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod b/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod new file mode 100644 index 0000000000..dc4d884c59 --- /dev/null +++ b/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +i2d_PKCS7_bio_stream - output PKCS7 structure in BER format. + +=head1 SYNOPSIS + + #include + + int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); + +=head1 DESCRIPTION + +i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format. + +It is otherwise identical to the function SMIME_write_PKCS7(). + +=head1 NOTES + +This function is effectively a version of the d2i_PKCS7_bio() supporting +streaming. + +=head1 BUGS + +The prefix "d2i" is arguably wrong because the function outputs BER format. + +=head1 RETURN VALUES + +i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L, L, +L, L +L, +L, +L + +=head1 HISTORY + +i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0 + +=cut -- cgit v1.2.3-55-g6feb