From ff48c0d9098080b51ea12710029135916d117806 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 30 Mar 2010 12:36:28 +0000 Subject: svn merge -r514:HEAD ^/branches/released . --- openssl/doc/crypto/ASN1_OBJECT_new.pod | 2 + openssl/doc/crypto/ASN1_STRING_length.pod | 2 + openssl/doc/crypto/ASN1_STRING_new.pod | 2 + openssl/doc/crypto/ASN1_generate_nconf.pod | 7 +- openssl/doc/crypto/BIO_f_md.pod | 6 + openssl/doc/crypto/BIO_f_ssl.pod | 9 + openssl/doc/crypto/BIO_new_CMS.pod | 66 +++++ openssl/doc/crypto/BIO_s_mem.pod | 2 +- openssl/doc/crypto/BN_BLINDING_new.pod | 20 +- openssl/doc/crypto/CMS_add0_cert.pod | 66 +++++ openssl/doc/crypto/CMS_add1_recipient_cert.pod | 62 +++++ openssl/doc/crypto/CMS_compress.pod | 73 +++++ openssl/doc/crypto/CMS_decrypt.pod | 65 +++++ openssl/doc/crypto/CMS_encrypt.pod | 96 +++++++ openssl/doc/crypto/CMS_final.pod | 41 +++ openssl/doc/crypto/CMS_get0_RecipientInfos.pod | 106 +++++++ openssl/doc/crypto/CMS_get0_SignerInfos.pod | 75 +++++ openssl/doc/crypto/CMS_get0_type.pod | 63 +++++ openssl/doc/crypto/CMS_get1_ReceiptRequest.pod | 69 +++++ openssl/doc/crypto/CMS_sign.pod | 121 ++++++++ openssl/doc/crypto/CMS_sign_add1_signer.pod | 101 +++++++ openssl/doc/crypto/CMS_sign_receipt.pod | 45 +++ openssl/doc/crypto/CMS_uncompress.pod | 54 ++++ openssl/doc/crypto/CMS_verify.pod | 126 +++++++++ openssl/doc/crypto/CMS_verify_receipt.pod | 47 ++++ openssl/doc/crypto/CRYPTO_set_ex_data.pod | 2 + openssl/doc/crypto/DSA_get_ex_new_index.pod | 2 +- openssl/doc/crypto/EVP_DigestInit.pod | 23 +- openssl/doc/crypto/EVP_DigestSignInit.pod | 87 ++++++ openssl/doc/crypto/EVP_DigestVerifyInit.pod | 82 ++++++ openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod | 128 +++++++++ openssl/doc/crypto/EVP_PKEY_CTX_new.pod | 52 ++++ openssl/doc/crypto/EVP_PKEY_cmp.pod | 61 +++++ openssl/doc/crypto/EVP_PKEY_decrypt.pod | 93 +++++++ openssl/doc/crypto/EVP_PKEY_derive.pod | 93 +++++++ openssl/doc/crypto/EVP_PKEY_encrypt.pod | 93 +++++++ openssl/doc/crypto/EVP_PKEY_get_default_digest.pod | 41 +++ openssl/doc/crypto/EVP_PKEY_keygen.pod | 161 +++++++++++ openssl/doc/crypto/EVP_PKEY_print_private.pod | 53 ++++ openssl/doc/crypto/EVP_PKEY_sign.pod | 96 +++++++ openssl/doc/crypto/EVP_PKEY_verify.pod | 91 +++++++ openssl/doc/crypto/EVP_PKEY_verifyrecover.pod | 103 +++++++ openssl/doc/crypto/EVP_SignInit.pod | 9 + openssl/doc/crypto/EVP_VerifyInit.pod | 9 + openssl/doc/crypto/OBJ_nid2obj.pod | 2 + openssl/doc/crypto/PEM_write_bio_CMS_stream.pod | 41 +++ openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod | 41 +++ openssl/doc/crypto/PKCS12_parse.pod | 31 ++- openssl/doc/crypto/PKCS7_decrypt.pod | 4 +- openssl/doc/crypto/PKCS7_encrypt.pod | 61 +++-- openssl/doc/crypto/PKCS7_sign.pod | 115 ++++---- openssl/doc/crypto/PKCS7_sign_add_signer.pod | 87 ++++++ openssl/doc/crypto/PKCS7_verify.pod | 6 +- openssl/doc/crypto/SMIME_read_CMS.pod | 70 +++++ openssl/doc/crypto/SMIME_read_PKCS7.pod | 4 +- openssl/doc/crypto/SMIME_write_CMS.pod | 64 +++++ openssl/doc/crypto/SMIME_write_PKCS7.pod | 24 +- openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod | 16 +- openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod | 12 +- openssl/doc/crypto/X509_NAME_get_index_by_NID.pod | 14 +- openssl/doc/crypto/X509_STORE_CTX_get_error.pod | 303 +++++++++++++++++++++ .../doc/crypto/X509_STORE_CTX_get_ex_new_index.pod | 41 +++ openssl/doc/crypto/X509_STORE_CTX_new.pod | 122 +++++++++ .../doc/crypto/X509_STORE_CTX_set_verify_cb.pod | 161 +++++++++++ .../doc/crypto/X509_STORE_set_verify_cb_func.pod | 54 ++++ openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod | 171 ++++++++++++ openssl/doc/crypto/X509_new.pod | 2 + openssl/doc/crypto/X509_verify_cert.pod | 53 ++++ openssl/doc/crypto/bn_internal.pod | 30 +- openssl/doc/crypto/d2i_RSAPublicKey.pod | 8 +- openssl/doc/crypto/d2i_X509.pod | 12 +- openssl/doc/crypto/d2i_X509_CRL.pod | 4 +- openssl/doc/crypto/d2i_X509_REQ.pod | 4 +- openssl/doc/crypto/evp.pod | 22 +- openssl/doc/crypto/hmac.pod | 22 +- openssl/doc/crypto/i2d_CMS_bio_stream.pod | 44 +++ openssl/doc/crypto/i2d_PKCS7_bio_stream.pod | 44 +++ openssl/doc/crypto/lhash.pod | 244 +++++++++-------- openssl/doc/crypto/pem.pod | 2 +- openssl/doc/crypto/threads.pod | 91 +++++-- openssl/doc/crypto/ui_compat.pod | 2 + 81 files changed, 4310 insertions(+), 323 deletions(-) create mode 100644 openssl/doc/crypto/BIO_new_CMS.pod create mode 100644 openssl/doc/crypto/CMS_add0_cert.pod create mode 100644 openssl/doc/crypto/CMS_add1_recipient_cert.pod create mode 100644 openssl/doc/crypto/CMS_compress.pod create mode 100644 openssl/doc/crypto/CMS_decrypt.pod create mode 100644 openssl/doc/crypto/CMS_encrypt.pod create mode 100644 openssl/doc/crypto/CMS_final.pod create mode 100644 openssl/doc/crypto/CMS_get0_RecipientInfos.pod create mode 100644 openssl/doc/crypto/CMS_get0_SignerInfos.pod create mode 100644 openssl/doc/crypto/CMS_get0_type.pod create mode 100644 openssl/doc/crypto/CMS_get1_ReceiptRequest.pod create mode 100644 openssl/doc/crypto/CMS_sign.pod create mode 100644 openssl/doc/crypto/CMS_sign_add1_signer.pod create mode 100644 openssl/doc/crypto/CMS_sign_receipt.pod create mode 100644 openssl/doc/crypto/CMS_uncompress.pod create mode 100644 openssl/doc/crypto/CMS_verify.pod create mode 100644 openssl/doc/crypto/CMS_verify_receipt.pod create mode 100644 openssl/doc/crypto/EVP_DigestSignInit.pod create mode 100644 openssl/doc/crypto/EVP_DigestVerifyInit.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_CTX_new.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_cmp.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_decrypt.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_derive.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_encrypt.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_get_default_digest.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_keygen.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_print_private.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_sign.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_verify.pod create mode 100644 openssl/doc/crypto/EVP_PKEY_verifyrecover.pod create mode 100644 openssl/doc/crypto/PEM_write_bio_CMS_stream.pod create mode 100644 openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod create mode 100644 openssl/doc/crypto/PKCS7_sign_add_signer.pod create mode 100644 openssl/doc/crypto/SMIME_read_CMS.pod create mode 100644 openssl/doc/crypto/SMIME_write_CMS.pod create mode 100644 openssl/doc/crypto/X509_STORE_CTX_get_error.pod create mode 100644 openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod create mode 100644 openssl/doc/crypto/X509_STORE_CTX_new.pod create mode 100644 openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod create mode 100644 openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod create mode 100644 openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod create mode 100644 openssl/doc/crypto/X509_verify_cert.pod create mode 100644 openssl/doc/crypto/i2d_CMS_bio_stream.pod create mode 100644 openssl/doc/crypto/i2d_PKCS7_bio_stream.pod (limited to 'openssl/doc/crypto') diff --git a/openssl/doc/crypto/ASN1_OBJECT_new.pod b/openssl/doc/crypto/ASN1_OBJECT_new.pod index 51679bfcd..9bae40fcc 100644 --- a/openssl/doc/crypto/ASN1_OBJECT_new.pod +++ b/openssl/doc/crypto/ASN1_OBJECT_new.pod @@ -6,6 +6,8 @@ ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions =head1 SYNOPSIS + #include + ASN1_OBJECT *ASN1_OBJECT_new(void); void ASN1_OBJECT_free(ASN1_OBJECT *a); diff --git a/openssl/doc/crypto/ASN1_STRING_length.pod b/openssl/doc/crypto/ASN1_STRING_length.pod index c4ec693f1..a08e9a0fa 100644 --- a/openssl/doc/crypto/ASN1_STRING_length.pod +++ b/openssl/doc/crypto/ASN1_STRING_length.pod @@ -8,6 +8,8 @@ ASN1_STRING utility functions =head1 SYNOPSIS + #include + int ASN1_STRING_length(ASN1_STRING *x); unsigned char * ASN1_STRING_data(ASN1_STRING *x); diff --git a/openssl/doc/crypto/ASN1_STRING_new.pod b/openssl/doc/crypto/ASN1_STRING_new.pod index 5b1bbb7eb..8ac2a03ae 100644 --- a/openssl/doc/crypto/ASN1_STRING_new.pod +++ b/openssl/doc/crypto/ASN1_STRING_new.pod @@ -7,6 +7,8 @@ ASN1_STRING allocation functions =head1 SYNOPSIS + #include + ASN1_STRING * ASN1_STRING_new(void); ASN1_STRING * ASN1_STRING_type_new(int type); void ASN1_STRING_free(ASN1_STRING *a); diff --git a/openssl/doc/crypto/ASN1_generate_nconf.pod b/openssl/doc/crypto/ASN1_generate_nconf.pod index 1157cff51..542fd1579 100644 --- a/openssl/doc/crypto/ASN1_generate_nconf.pod +++ b/openssl/doc/crypto/ASN1_generate_nconf.pod @@ -6,6 +6,8 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions =head1 SYNOPSIS + #include + ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf); @@ -101,7 +103,8 @@ bits is set to zero. =item B, B, B, B, B, B, B, B, B, B, B, B, B, -B, B, B +B, B, B, B, +B These encode the corresponding string types. B represents the contents of this structure. The format can be B or B. @@ -175,7 +178,7 @@ An IA5String explicitly tagged using APPLICATION tagging: A BITSTRING with bits 1 and 5 set and all others zero: - FORMAT=BITLIST,BITSTRING:1,5 + FORMAT:BITLIST,BITSTRING:1,5 A more complex example using a config file to produce a SEQUENCE consiting of a BOOL an OID and a UTF8String: diff --git a/openssl/doc/crypto/BIO_f_md.pod b/openssl/doc/crypto/BIO_f_md.pod index 0d24083e6..2cc41f89d 100644 --- a/openssl/doc/crypto/BIO_f_md.pod +++ b/openssl/doc/crypto/BIO_f_md.pod @@ -58,6 +58,12 @@ If an application needs to call BIO_gets() or BIO_puts() through a chain containing digest BIOs then this can be done by prepending a buffering BIO. +Before OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO +had been initialized for example by calling BIO_set_md() ). In OpenSSL +1.0.0 and later the context is always returned and the BIO is state is set +to initialized. This allows applications to initialize the context externally +if the standard calls such as BIO_set_md() are not sufficiently flexible. + =head1 RETURN VALUES BIO_f_md() returns the digest BIO method. diff --git a/openssl/doc/crypto/BIO_f_ssl.pod b/openssl/doc/crypto/BIO_f_ssl.pod index f0b731731..bc5861ab3 100644 --- a/openssl/doc/crypto/BIO_f_ssl.pod +++ b/openssl/doc/crypto/BIO_f_ssl.pod @@ -308,6 +308,15 @@ a client and also echoes the request to standard output. BIO_free_all(sbio); +=head1 BUGS + +In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, +the I/O BIO reference count was incorrectly incremented (instead of +decremented) and dissociated with the SSL BIO even if the SSL BIO was not +explicitly being popped (e.g. a pop higher up the chain). Applications which +included workarounds for this bug (e.g. freeing BIOs more than once) should +be modified to handle this fix or they may free up an already freed BIO. + =head1 SEE ALSO TBA diff --git a/openssl/doc/crypto/BIO_new_CMS.pod b/openssl/doc/crypto/BIO_new_CMS.pod new file mode 100644 index 000000000..9e3a4b7f8 --- /dev/null +++ b/openssl/doc/crypto/BIO_new_CMS.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + + BIO_new_CMS - CMS streaming filter BIO + +=head1 SYNOPSIS + + #include + + BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +BIO_new_CMS() returns a streaming filter BIO chain based on B. The output +of the filter is written to B. Any data written to the chain is +automatically translated to a BER format CMS structure of the appropriate type. + +=head1 NOTES + +The chain returned by this function behaves like a standard filter BIO. It +supports non blocking I/O. Content is processed and streamed on the fly and not +all held in memory at once: so it is possible to encode very large structures. +After all content has been written through the chain BIO_flush() must be called +to finalise the structure. + +The B flag must be included in the corresponding B +parameter of the B creation function. + +If an application wishes to write additional data to B BIOs should be +removed from the chain using BIO_pop() and freed with BIO_free() until B +is reached. If no additional data needs to be written BIO_free_all() can be +called to free up the whole chain. + +Any content written through the filter is used verbatim: no canonical +translation is performed. + +It is possible to chain multiple BIOs to, for example, create a triple wrapped +signed, enveloped, signed structure. In this case it is the applications +responsibility to set the inner content type of any outer CMS_ContentInfo +structures. + +Large numbers of small writes through the chain should be avoided as this will +produce an output consisting of lots of OCTET STRING structures. Prepending +a BIO_f_buffer() buffering BIO will prevent this. + +=head1 BUGS + +There is currently no corresponding inverse BIO: i.e. one which can decode +a CMS structure on the fly. + +=head1 RETURN VALUES + +BIO_new_CMS() returns a BIO chain when successful or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L, +L + +=head1 HISTORY + +BIO_new_CMS() was added to OpenSSL 1.0.0 + +=cut diff --git a/openssl/doc/crypto/BIO_s_mem.pod b/openssl/doc/crypto/BIO_s_mem.pod index 19648acfa..8f85e0dce 100644 --- a/openssl/doc/crypto/BIO_s_mem.pod +++ b/openssl/doc/crypto/BIO_s_mem.pod @@ -74,7 +74,7 @@ Writes to memory BIOs will always succeed if memory is available: that is their size can grow indefinitely. Every read from a read write memory BIO will remove the data just read with -an internal copy operation, if a BIO contains a lots of data and it is +an internal copy operation, if a BIO contains a lot of data and it is read in small chunks the operation can be very slow. The use of a read only memory BIO avoids this problem. If the BIO must be read write then adding a buffering BIO to the chain will speed up the process. diff --git a/openssl/doc/crypto/BN_BLINDING_new.pod b/openssl/doc/crypto/BN_BLINDING_new.pod index 7b087f728..5f51fdb47 100644 --- a/openssl/doc/crypto/BN_BLINDING_new.pod +++ b/openssl/doc/crypto/BN_BLINDING_new.pod @@ -22,8 +22,11 @@ functions. BN_CTX *ctx); int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b, BN_CTX *ctx); + #ifndef OPENSSL_NO_DEPRECATED unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); + #endif + CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *); unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, @@ -54,11 +57,11 @@ BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() with B set to NULL. -BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id() -set and get the "thread id" value of the B structure, -a field provided to users of B structure to help them -provide proper locking if needed for multi-threaded use. The -"thread id" of a newly allocated B structure is zero. +BN_BLINDING_thread_id() provides access to the B +object within the B structure. This is to help users +provide proper locking if needed for multi-threaded use. The "thread +id" object of a newly allocated B structure is +initialised to the thread id in which BN_BLINDING_new() was called. BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently there are two supported flags: B and @@ -83,8 +86,8 @@ BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(), BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on success and 0 if an error occured. -BN_BLINDING_get_thread_id() returns the thread id (a B -value) or 0 if not set. +BN_BLINDING_thread_id() returns a pointer to the thread id object +within a B object. BN_BLINDING_get_flags() returns the currently set B flags (a B value). @@ -98,6 +101,9 @@ L =head1 HISTORY +BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it +deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id. + BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8 diff --git a/openssl/doc/crypto/CMS_add0_cert.pod b/openssl/doc/crypto/CMS_add0_cert.pod new file mode 100644 index 000000000..9c13f488f --- /dev/null +++ b/openssl/doc/crypto/CMS_add0_cert.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + + CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_get1_crls, - CMS certificate and CRL utility functions + +=head1 SYNOPSIS + + #include + + int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert); + int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert); + STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms); + + int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl); + int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl); + STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms); + + +=head1 DESCRIPTION + +CMS_add0_cert() and CMS_add1_cert() add certificate B to B. +must be of type signed data or enveloped data. + +CMS_get1_certs() returns all certificates in B. + +CMS_add0_crl() and CMS_add1_crl() add CRL B to B. CMS_get1_crls() +returns any CRLs in B. + +=head1 NOTES + +The CMS_ContentInfo structure B must be of type signed data or enveloped +data or an error will be returned. + +For signed data certificates and CRLs are added to the B and +B fields of SignedData structure. For enveloped data they are added to +B. + +As the B<0> implies CMS_add0_cert() adds B internally to B and it +must not be freed up after the call as opposed to CMS_add1_cert() where B +must be freed up. + +The same certificate or CRL must not be added to the same cms structure more +than once. + +=head1 RETURN VALUES + +CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return +1 for success and 0 for failure. + +CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs +or NULL if there are none or an error occurs. The only error which will occur +in practice is if the B type is invalid. + +=head1 SEE ALSO + +L, +L, +L + +=head1 HISTORY + +CMS_add0_cert(), CMS_add1_cert(), CMS_get1_certs(), CMS_add0_crl() +and CMS_get1_crls() were all first added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_add1_recipient_cert.pod b/openssl/doc/crypto/CMS_add1_recipient_cert.pod new file mode 100644 index 000000000..d7d8e2532 --- /dev/null +++ b/openssl/doc/crypto/CMS_add1_recipient_cert.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + + CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure + +=head1 SYNOPSIS + + #include + + CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags); + + CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType); + +=head1 DESCRIPTION + +CMS_add1_recipient_cert() adds recipient B to CMS_ContentInfo enveloped +data structure B as a KeyTransRecipientInfo structure. + +CMS_add0_recipient_key() adds symmetric key B of length B using +wrapping algorithm B, identifier B of length B and optional +values B, B and B to CMS_ContentInfo enveloped +data structure B as a KEKRecipientInfo structure. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_encrypt() with the flag B set. + +=head1 NOTES + +The main purpose of this function is to provide finer control over a CMS +enveloped data structure where the simpler CMS_encrypt() function defaults are +not appropriate. For example if one or more KEKRecipientInfo structures +need to be added. New attributes can also be added using the returned +CMS_RecipientInfo structure and the CMS attribute utility functions. + +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If B is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. + +Currently only AES based key wrapping algorithms are supported for B, +specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. +If B is set to B then an AES wrap algorithm will be used +consistent with B. + +=head1 RETURN VALUES + +CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal +pointer to the CMS_RecipientInfo structure just added or NULL if an error +occurs. + +=head1 SEE ALSO + +L, L, +L, + +=head1 HISTORY + +CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL +0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_compress.pod b/openssl/doc/crypto/CMS_compress.pod new file mode 100644 index 000000000..0a0715271 --- /dev/null +++ b/openssl/doc/crypto/CMS_compress.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +CMS_compress - create a CMS CompressedData structure + +=head1 SYNOPSIS + + #include + + CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags); + +=head1 DESCRIPTION + +CMS_compress() creates and returns a CMS CompressedData structure. B +is the compression algorithm to use or B to use the default +algorithm (zlib compression). B is the content to be compressed. +B is an optional set of flags. + +=head1 NOTES + +The only currently supported compression algorithm is zlib using the NID +NID_zlib_compression. + +If zlib support is not compiled into OpenSSL then CMS_compress() will return +an error. + +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. + +If the B flag is set a partial B structure is +returned suitable for streaming I/O: no data is read from the BIO B. + +The compressed data is included in the CMS_ContentInfo structure, unless +B is set in which case it is omitted. This is rarely used in +practice and is not supported by SMIME_write_CMS(). + +=head1 NOTES + +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. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B directly using +BIO_new_CMS(). + +Additional compression parameters such as the zlib compression level cannot +currently be set. + +=head1 RETURN VALUES + +CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +CMS_compress() was added to OpenSSL 0.9.8 +The B flag was first supported in OpenSSL 1.0.0. + +=cut diff --git a/openssl/doc/crypto/CMS_decrypt.pod b/openssl/doc/crypto/CMS_decrypt.pod new file mode 100644 index 000000000..d857e4f93 --- /dev/null +++ b/openssl/doc/crypto/CMS_decrypt.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + + CMS_decrypt - decrypt content from a CMS envelopedData structure + +=head1 SYNOPSIS + + #include + + int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags); + +=head1 DESCRIPTION + +CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData +structure. B is the private key of the recipient, B is the +recipient's certificate, B is a BIO to write the content to and +B is an optional set of flags. + +The B parameter is used in the rare case where the encrypted content +is detached. It will normally be set to NULL. + +=head1 NOTES + +OpenSSL_add_all_algorithms() (or equivalent) should be called before using this +function or errors about unknown algorithms will occur. + +Although the recipients certificate is not needed to decrypt the data it is +needed to locate the appropriate (of possible several) recipients in the CMS +structure. If B is set to NULL all possible recipients are tried. + +It is possible to determine the correct recipient key by other means (for +example looking them up in a database) and setting them in the CMS structure +in advance using the CMS utility functions such as CMS_set1_pkey(). In this +case both B and B should be set to NULL. + +To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() +and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and +B and B set to NULL. + +The following flags can be passed in the B parameter. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B then an error is +returned. + +=head1 RETURN VALUES + +CMS_decrypt() returns either 1 for success or 0 for failure. +The error can be obtained from ERR_get_error(3) + +=head1 BUGS + +The lack of single pass processing and the need to hold all data in memory as +mentioned in CMS_verify() also applies to CMS_decrypt(). + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +CMS_decrypt() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_encrypt.pod b/openssl/doc/crypto/CMS_encrypt.pod new file mode 100644 index 000000000..1ee5b275e --- /dev/null +++ b/openssl/doc/crypto/CMS_encrypt.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + + CMS_encrypt - create a CMS envelopedData structure + +=head1 SYNOPSIS + + #include + + CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags); + +=head1 DESCRIPTION + +CMS_encrypt() creates and returns a CMS EnvelopedData structure. B +is a list of recipient certificates. B is the content to be encrypted. +B is the symmetric cipher to use. B is an optional set of flags. + +=head1 NOTES + +Only certificates carrying RSA keys are supported 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. + +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 +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 +CMS_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. + +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. + +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If B is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. + +If the B flag is set a partial B structure is +returned suitable for streaming I/O: no data is read from the BIO B. + +If the B flag is set a partial B structure is +returned to which additional recipients and attributes can be added before +finalization. + +The data being encrypted is included in the CMS_ContentInfo structure, unless +B is set in which case it is omitted. This is rarely used in +practice and is not supported by SMIME_write_CMS(). + +=head1 NOTES + +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. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B directly using +BIO_new_CMS(). + +The recipients specified in B use a CMS KeyTransRecipientInfo info +structure. KEKRecipientInfo is also supported using the flag B +and CMS_add0_recipient_key(). + +The parameter B may be NULL if B is set and recipients +added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key(). + +=head1 RETURN VALUES + +CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +CMS_decrypt() was added to OpenSSL 0.9.8 +The B flag was first supported in OpenSSL 1.0.0. + +=cut diff --git a/openssl/doc/crypto/CMS_final.pod b/openssl/doc/crypto/CMS_final.pod new file mode 100644 index 000000000..36cf96b8a --- /dev/null +++ b/openssl/doc/crypto/CMS_final.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + + CMS_final - finalise a CMS_ContentInfo structure + +=head1 SYNOPSIS + + #include + + int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); + +=head1 DESCRIPTION + +CMS_final() finalises the structure B. It's purpose is to perform any +operations necessary on B (digest computation for example) and set the +appropriate fields. The parameter B contains the content to be +processed. The B parameter contains a BIO to write content to after +processing: this is only used with detached data and will usually be set to +NULL. + +=head1 NOTES + +This function will normally be called when the B flag is used. It +should only be used when streaming is not performed because the streaming +I/O functions perform finalisation operations internally. + +=head1 RETURN VALUES + +CMS_final() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L, L, +L + +=head1 HISTORY + +CMS_final() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get0_RecipientInfos.pod b/openssl/doc/crypto/CMS_get0_RecipientInfos.pod new file mode 100644 index 000000000..e0355423e --- /dev/null +++ b/openssl/doc/crypto/CMS_get0_RecipientInfos.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + + CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines + +=head1 SYNOPSIS + + #include + + STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms); + int CMS_RecipientInfo_type(CMS_RecipientInfo *ri); + + int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); + int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert); + int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey); + + int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype); + int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen); + int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen); + + int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); + +=head1 DESCRIPTION + +The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo +structures associated with a CMS EnvelopedData structure. + +CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B. +It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, +CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. + +CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient +identifier associated with a specific CMS_RecipientInfo structure B, which +must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in +B or B issuer name and serial number in B and B. + +CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B against the +CMS_RecipientInfo structure B, which must be of type CMS_RECIPINFO_TRANS. +It returns zero if the comparison is successful and non zero if not. + +CMS_RecipientInfo_set0_pkey() associates the private key B with +the CMS_RecipientInfo structure B, which must be of type +CMS_RECIPINFO_TRANS. + +CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the +CMS_RecipientInfo structure B which must be of type CMS_RECIPINFO_KEK. Any +of the remaining parameters can be NULL if the application is not interested in +the value of a field. Where a field is optional and absent NULL will be written +to the corresponding parameter. The keyEncryptionAlgorithm field is written to +B, the B field is written to B, the B field if +present is written to B, if the B field is present the components +B and B are written to parameters B and +B. + +CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B and B +parameters against the B CMS_RecipientInfo structure B, +which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is +successful and non zero if not. + +CMS_RecipientInfo_set0_key() associates the symmetric key B of length +B with the CMS_RecipientInfo structure B, which must be of type +CMS_RECIPINFO_KEK. + +CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure +B in structure B. A key must have been associated with the structure +first. + +=head1 NOTES + +The main purpose of these functions is to enable an application to lookup +recipient keys using any appropriate technique when the simpler method +of CMS_decrypt() is not appropriate. + +In typical usage and application will retrieve all CMS_RecipientInfo structures +using CMS_get0_RecipientInfos() and check the type of each using +CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure +can be ignored or its key identifier data retrieved using an appropriate +function. Then if the corresponding secret or private key can be obtained by +any appropriate means it can then associated with the structure and +CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called +with a NULL key to decrypt the enveloped content. + +=head1 RETURN VALUES + +CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if +an error occurs. + +CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), +CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and +CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. + +CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 +for a successful comparison and non zero otherwise. + +Any error can be obtained from L. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +These functions were first was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get0_SignerInfos.pod b/openssl/doc/crypto/CMS_get0_SignerInfos.pod new file mode 100644 index 000000000..47f6d2a04 --- /dev/null +++ b/openssl/doc/crypto/CMS_get0_SignerInfos.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + + CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions. + +=head1 SYNOPSIS + + #include + + STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms); + + int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); + int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert); + void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer); + +=head1 DESCRIPTION + +The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures +associated with a CMS signedData structure. + +CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier +associated with a specific CMS_SignerInfo structure B. Either the +keyidentifier will be set in B or B issuer name and serial number +in B and B. + +CMS_SignerInfo_cert_cmp() compares the certificate B against the signer +identifier B. It returns zero if the comparison is successful and non zero +if not. + +CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B to +B. + +=head1 NOTES + +The main purpose of these functions is to enable an application to lookup +signers certificates using any appropriate technique when the simpler method +of CMS_verify() is not appropriate. + +In typical usage and application will retrieve all CMS_SignerInfo structures +using CMS_get0_SignerInfo() and retrieve the identifier information using +CMS. It will then obtain the signer certificate by some unspecified means +(or return and error if it cannot be found) and set it using +CMS_SignerInfo_set1_signer_cert(). + +Once all signer certificates have been set CMS_verify() can be used. + +Although CMS_get0_SignerInfos() can return NULL is an error occur B if +there are no signers this is not a problem in practice because the only +error which can occur is if the B structure is not of type signedData +due to application error. + +=head1 RETURN VALUES + +CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there +are no signers or an error occurs. + +CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure. + +CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non +zero otherwise. + +CMS_SignerInfo_set1_signer_cert() does not return a value. + +Any error can be obtained from L + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +These functions were first was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get0_type.pod b/openssl/doc/crypto/CMS_get0_type.pod new file mode 100644 index 000000000..8ff1c3115 --- /dev/null +++ b/openssl/doc/crypto/CMS_get0_type.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + + CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types + +=head1 SYNOPSIS + + #include + + const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms); + int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid); + const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +CMS_get0_type() returns the content type of a CMS_ContentInfo structure as +and ASN1_OBJECT pointer. An application can then decide how to process the +CMS_ContentInfo structure based on this value. + +CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo +structure. It should be called with CMS functions with the B +flag and B the structure is finalised, otherwise the results are +undefined. + +ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded +content type. + +=head1 NOTES + +As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal +pointers which should B be freed up. CMS_set1_eContentType() copies the +supplied OID and it B be freed up after use. + +The B values returned can be converted to an integer B value +using OBJ_obj2nid(). For the currently supported content types the following +values are returned: + + NID_pkcs7_data + NID_pkcs7_signed + NID_pkcs7_digest + NID_id_smime_ct_compressedData: + NID_pkcs7_encrypted + NID_pkcs7_enveloped + + +=head1 RETURN VALUES + +CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure. + +CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The +error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L + +=head1 HISTORY + +CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all +first added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod b/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod new file mode 100644 index 000000000..f546376a1 --- /dev/null +++ b/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + + CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions. + +=head1 SYNOPSIS + + #include + + CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); + int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); + int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); + void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto); + +=head1 DESCRIPTION + +CMS_ReceiptRequest_create0() creates a signed receipt request structure. The +B field is set using B and B, or it is set +to 32 bytes of pseudo random data if B is NULL. If B is NULL +the allOrFirstTier option in B is used and set to the value of +the B parameter. If B is not NULL the B +option in B is used. The B parameter specifies the +B field value. + +The CMS_add1_ReceiptRequest() function adds a signed receipt request B +to SignerInfo structure B. + +int CMS_get1_ReceiptRequest() looks for a signed receipt request in B, if +any is found it is decoded and written to B. + +CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. +The signedContentIdentifier is copied to B. If the B +option of B is used its value is copied to B +otherwise the B field is copied to B. The B +parameter is copied to B. + +=head1 NOTES + +For more details of the meaning of the fields see RFC2634. + +The contents of a signed receipt should only be considered meaningful if the +corresponding CMS_ContentInfo structure can be successfully verified using +CMS_verify(). + +=head1 RETURN VALUES + +CMS_ReceiptRequest_create0() returns a signed receipt request structure or +NULL if an error occurred. + +CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred. + +CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and +decoded. It returns 0 if a signed receipt request is not present and -1 if +it is present but malformed. + +=head1 SEE ALSO + +L, L, +L, L +L + +=head1 HISTORY + +CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), +CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to +OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_sign.pod b/openssl/doc/crypto/CMS_sign.pod new file mode 100644 index 000000000..2cc72de32 --- /dev/null +++ b/openssl/doc/crypto/CMS_sign.pod @@ -0,0 +1,121 @@ +=pod + +=head1 NAME + + CMS_sign - create a CMS SignedData structure + +=head1 SYNOPSIS + + #include + + CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags); + +=head1 DESCRIPTION + +CMS_sign() creates and returns a CMS SignedData structure. B is +the certificate to sign with, B is the corresponding private key. +B is an optional additional set of certificates to include in the CMS +structure (for example any intermediate CAs in the chain). Any or all of +these parameters can be B, see B below. + +The data to be signed is read from BIO B. + +B is an optional set of flags. + +=head1 NOTES + +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 +CMS_ContentInfo 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 CMS_ContentInfo structure, unless +B is set in which case it is omitted. This is used for +CMS_ContentInfo 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 CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If B is set then no signedAttributes +will be used. If B is set then just the SMIMECapabilities are +omitted. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. + +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 the B flag is set a partial B structure is +output to which additional signers and capabilities can be added before +finalization. + +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. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B directly using +BIO_new_CMS(). + +If a signer is specified it will use the default digest for the signing +algorithm. This is B for both RSA and DSA keys. + +If B and B are NULL then a certificates only CMS structure is +output. + +The function CMS_sign() is a basic CMS signing function whose output will be +suitable for many purposes. For finer control of the output format the +B, B and B parameters can all be B and the +B flag set. Then one or more signers can be added using the +function CMS_sign_add1_signer(), non default digests can be used and custom +attributes added. B must then be called to finalize the +structure if streaming is not enabled. + +=head1 BUGS + +Some attributes such as counter signatures are not supported. + +=head1 RETURN VALUES + +CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +CMS_sign() was added to OpenSSL 0.9.8 + +The B flag is only supported for detached data in OpenSSL 0.9.8, +it is supported for embedded data in OpenSSL 1.0.0 and later. + +=cut diff --git a/openssl/doc/crypto/CMS_sign_add1_signer.pod b/openssl/doc/crypto/CMS_sign_add1_signer.pod new file mode 100644 index 000000000..bda3ca2ad --- /dev/null +++ b/openssl/doc/crypto/CMS_sign_add1_signer.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + + CMS_sign_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. + +=head1 SYNOPSIS + + #include + + CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); + + int CMS_SignerInfo_sign(CMS_SignerInfo *si); + + +=head1 DESCRIPTION + +CMS_sign_add1_signer() adds a signer with certificate B and private +key B using message digest B to CMS_ContentInfo SignedData +structure B. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_sign() with the flag B set or in the case or re-signing a +valid CMS_ContentInfo SignedData 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 CMS_ContentInfo +structure is not complete and must be finalized either by streaming (if +applicable) or a call to CMS_final(). + +The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo +structure, its main use is when B and B flags +are both set. + +=head1 NOTES + +The main purpose of CMS_sign_add1_signer() is to provide finer control +over a CMS signed data structure where the simpler CMS_sign() function defaults +are not appropriate. For example if multiple signers or non default digest +algorithms are needed. New attributes can also be added using the returned +CMS_SignerInfo structure and the CMS attribute utility functions or the +CMS signed receipt request functions. + +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 CMS_ContentInfo structure: to add a signer to an existing +structure. An error occurs if a matching digest value cannot be found to copy. +The returned CMS_ContentInfo structure will be valid and finalized when this +flag is set. + +If B is set in addition to B then the +CMS_SignerInfo structure will not be finalized so additional attributes +can be added. In this case an explicit call to CMS_SignerInfo_sign() is +needed to finalize it. + +If B is set the signer's certificate will not be included in the +CMS_ContentInfo 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 CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If B is set then no signedAttributes +will be used. If B is set then just the SMIMECapabilities are +omitted. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. + +CMS_sign_add1_signer() returns an internal pointer to the CMS_SignerInfo +structure just added, this can be used to set additional attributes +before it is finalized. + +=head1 RETURN VALUES + +CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo +structure just added or NULL if an error occurs. + +=head1 SEE ALSO + +L, L, +L, + +=head1 HISTORY + +CMS_sign_add1_signer() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_sign_receipt.pod b/openssl/doc/crypto/CMS_sign_receipt.pod new file mode 100644 index 000000000..cae1f8338 --- /dev/null +++ b/openssl/doc/crypto/CMS_sign_receipt.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + + CMS_sign_receipt - create a CMS signed receipt + +=head1 SYNOPSIS + + #include + + CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags); + +=head1 DESCRIPTION + +CMS_sign_receipt() creates and returns a CMS signed receipt structure. B is +the B structure containing the signed receipt request. +B is the certificate to sign with, B is the corresponding +private key. B is an optional additional set of certificates to include +in the CMS structure (for example any intermediate CAs in the chain). + +B is an optional set of flags. + +=head1 NOTES + +This functions behaves in a similar way to CMS_sign() except the flag values +B, B, B, B and B +are not supported since they do not make sense in the context of signed +receipts. + +=head1 RETURN VALUES + +CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if +an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, +L, +L + +=head1 HISTORY + +CMS_sign_receipt() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_uncompress.pod b/openssl/doc/crypto/CMS_uncompress.pod new file mode 100644 index 000000000..c6056b027 --- /dev/null +++ b/openssl/doc/crypto/CMS_uncompress.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + + CMS_uncompress - uncompress a CMS CompressedData structure + +=head1 SYNOPSIS + + #include + + int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags); + +=head1 DESCRIPTION + +CMS_uncompress() extracts and uncompresses the content from a CMS +CompressedData structure B. B is a BIO to write the content to and +B is an optional set of flags. + +The B parameter is used in the rare case where the compressed content +is detached. It will normally be set to NULL. + +=head1 NOTES + +The only currently supported compression algorithm is zlib: if the structure +indicates the use of any other algorithm an error is returned. + +If zlib support is not compiled into OpenSSL then CMS_uncompress() will always +return an error. + +The following flags can be passed in the B parameter. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B then an error is +returned. + +=head1 RETURN VALUES + +CMS_uncompress() returns either 1 for success or 0 for failure. The error can +be obtained from ERR_get_error(3) + +=head1 BUGS + +The lack of single pass processing and the need to hold all data in memory as +mentioned in CMS_verify() also applies to CMS_decompress(). + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +CMS_uncompress() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_verify.pod b/openssl/doc/crypto/CMS_verify.pod new file mode 100644 index 000000000..8f26fdab0 --- /dev/null +++ b/openssl/doc/crypto/CMS_verify.pod @@ -0,0 +1,126 @@ +=pod + +=head1 NAME + + CMS_verify - verify a CMS SignedData structure + +=head1 SYNOPSIS + + #include + + int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags); + + STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +CMS_verify() verifies a CMS SignedData structure. B is the CMS_ContentInfo +structure to verify. B is a set of certificates in which to search for +the signing certificate(s). B is a trusted certificate store used for +chain verification. B is the detached content if the content is not +present in B. The content is written to B if it is not NULL. + +B is an optional set of flags, which can be used to modify the verify +operation. + +CMS_get0_signers() retrieves the signing certificate(s) from B, it must +be called after a successful CMS_verify() operation. + +=head1 VERIFY PROCESS + +Normally the verify process proceeds as follows. + +Initially some sanity checks are performed on B. The type of B must +be SignedData. There must be at least one signature on the data and if +the content is detached B cannot be B. + +An attempt is made to locate all the signing certificate(s), first looking in +the B parameter (if it is not NULL) and then looking in any +certificates contained in the B structure itself. If any signing +certificate cannot be located the operation fails. + +Each signing certificate is chain verified using the B purpose and +the supplied trusted certificate store. Any internal certificates in the message +are used as untrusted CAs. If CRL checking is enabled in B any internal +CRLs are used in addition to attempting to look them up in B. If any +chain verify fails an error code is returned. + +Finally the signed content is read (and written to B is it is not NULL) +and the signature's checked. + +If all signature's verify correctly then the function is successful. + +Any of the following flags (ored together) can be passed in the B +parameter to change the default verify behaviour. + +If B is set the certificates in the message itself are not +searched when locating the signing certificate(s). This means that all the +signing certificates must be in the B parameter. + +If B is set and CRL checking is enabled in B then any +CRLs in the message itself are ignored. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B then an error is +returned. + +If B is set the signing certificates are not +verified. + +If B is set the signed attributes signature is not +verified. + +If B is set then the content digest is not checked. + +=head1 NOTES + +One application of B is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the B parameter. In this case if the signer is not one of the +certificates supplied in B then the verify will fail because the +signer cannot be found. + +In some cases the standard techniques for looking up and validating +certificates are not appropriate: for example an application may wish to +lookup certificates in a database or perform customised verification. This +can be achieved by setting and verifying the signers certificates manually +using the signed data utility functions. + +Care should be taken when modifying the default verify behaviour, for example +setting B will totally disable all content verification +and any modified content will be considered valid. This combination is however +useful if one merely wishes to write the content to B and its validity +is not considered important. + +Chain verification should arguably be performed using the signing time rather +than the current time. However since the signing time is supplied by the +signer it cannot be trusted without additional evidence (such as a trusted +timestamp). + +=head1 RETURN VALUES + +CMS_verify() returns 1 for a successful verification and zero if an error +occurred. + +CMS_get0_signers() returns all signers or NULL if an error occurred. + +The error can be obtained from L + +=head1 BUGS + +The trusted certificate store is not searched for the signing certificate, +this is primarily due to the inadequacies of the current B +functionality. + +The lack of single pass processing means that the signed content must all +be held in memory if it is not detached. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +CMS_verify() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_verify_receipt.pod b/openssl/doc/crypto/CMS_verify_receipt.pod new file mode 100644 index 000000000..9283e0e04 --- /dev/null +++ b/openssl/doc/crypto/CMS_verify_receipt.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + + CMS_verify_receipt - verify a CMS signed receipt + +=head1 SYNOPSIS + + #include + + int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags); + +=head1 DESCRIPTION + +CMS_verify_receipt() verifies a CMS signed receipt. B is the signed +receipt to verify. B is the original SignedData structure containing the +receipt request. B is a set of certificates in which to search for the +signing certificate. B is a trusted certificate store (used for chain +verification). + +B is an optional set of flags, which can be used to modify the verify +operation. + +=head1 NOTES + +This functions behaves in a similar way to CMS_verify() except the flag values +B, B, B and B are not +supported since they do not make sense in the context of signed receipts. + +=head1 RETURN VALUES + +CMS_verify_receipt() returns 1 for a successful verification and zero if an +error occurred. + +The error can be obtained from L + +=head1 SEE ALSO + +L, +L, +L, + +=head1 HISTORY + +CMS_verify_receipt() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CRYPTO_set_ex_data.pod b/openssl/doc/crypto/CRYPTO_set_ex_data.pod index 1bd5bed67..7409c02aa 100644 --- a/openssl/doc/crypto/CRYPTO_set_ex_data.pod +++ b/openssl/doc/crypto/CRYPTO_set_ex_data.pod @@ -6,6 +6,8 @@ CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data func =head1 SYNOPSIS + #include + int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); diff --git a/openssl/doc/crypto/DSA_get_ex_new_index.pod b/openssl/doc/crypto/DSA_get_ex_new_index.pod index 4612e708e..fb6efc118 100644 --- a/openssl/doc/crypto/DSA_get_ex_new_index.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_DigestInit.pod b/openssl/doc/crypto/EVP_DigestInit.pod index 130cd7f60..5b477ac6e 100644 --- a/openssl/doc/crypto/EVP_DigestInit.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_DigestSignInit.pod b/openssl/doc/crypto/EVP_DigestSignInit.pod new file mode 100644 index 000000000..37d960e3b --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_DigestVerifyInit.pod b/openssl/doc/crypto/EVP_DigestVerifyInit.pod new file mode 100644 index 000000000..f22448897 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod b/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod new file mode 100644 index 000000000..f2f455990 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_CTX_new.pod b/openssl/doc/crypto/EVP_PKEY_CTX_new.pod new file mode 100644 index 000000000..a9af86758 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_cmp.pod b/openssl/doc/crypto/EVP_PKEY_cmp.pod new file mode 100644 index 000000000..4f8185e36 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_decrypt.pod b/openssl/doc/crypto/EVP_PKEY_decrypt.pod new file mode 100644 index 000000000..42b2a8c44 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_derive.pod b/openssl/doc/crypto/EVP_PKEY_derive.pod new file mode 100644 index 000000000..d9d6d76c7 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_encrypt.pod b/openssl/doc/crypto/EVP_PKEY_encrypt.pod new file mode 100644 index 000000000..91c9c5d0a --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_get_default_digest.pod b/openssl/doc/crypto/EVP_PKEY_get_default_digest.pod new file mode 100644 index 000000000..1a9c7954c --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_keygen.pod b/openssl/doc/crypto/EVP_PKEY_keygen.pod new file mode 100644 index 000000000..37c6fe950 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_print_private.pod b/openssl/doc/crypto/EVP_PKEY_print_private.pod new file mode 100644 index 000000000..ce9d70d7a --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_sign.pod b/openssl/doc/crypto/EVP_PKEY_sign.pod new file mode 100644 index 000000000..2fb52c348 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_verify.pod b/openssl/doc/crypto/EVP_PKEY_verify.pod new file mode 100644 index 000000000..10633da3f --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_PKEY_verifyrecover.pod b/openssl/doc/crypto/EVP_PKEY_verifyrecover.pod new file mode 100644 index 000000000..e2a2a8c6f --- /dev/null +++ b/openssl/doc/crypto/EVP_PKEY_verifyrecover.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +EVP_PKEY_verifyrecover_init, EVP_PKEY_verifyrecover - recover signature using a public key algorithm + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_verifyrecover_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_verifyrecover(EVP_PKEY_CTX *ctx, + unsigned char *rout, size_t *routlen, + const unsigned char *sig, size_t siglen); + +=head1 DESCRIPTION + +The EVP_PKEY_verifyrecover_init() function initializes a public key algorithm +context using key B for a verify recover operation. + +The EVP_PKEY_verifyrecover() function recovers signed data +using B. The signature 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 recovered data is written to +B and the amount of data written to B. + +=head1 NOTES + +Normally an application is only interested in whether a signature verification +operation is successful in those cases the EVP_verify() function should be +used. + +Sometimes however it is useful to obtain the data originally signed using a +signing operation. Only certain public key algorithms can recover a signature +in this way (for example RSA in PKCS padding mode). + +After the call to EVP_PKEY_verifyrecover_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_verifyrecover() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_verifyrecover_init() and EVP_PKEY_verifyrecover() 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 + +Recover digest originally signed using PKCS#1 and SHA256 digest: + + #include + #include + + EVP_PKEY_CTX *ctx; + unsigned char *rout, *sig; + size_t routlen, siglen; + EVP_PKEY *verify_key; + /* NB: assumes verify_key, sig and siglen 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_verifyrecover_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_verifyrecover(ctx, rout, &routlen, sig, siglen) <= 0) + /* Error */ + + rout = OPENSSL_malloc(routlen); + + if (!rout) + /* malloc failure */ + + if (EVP_PKEY_verifyrecover(ctx, rout, &routlen, sig, siglen) <= 0) + /* Error */ + + /* Recovered data is routlen bytes written to buffer rout */ + +=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/openssl/doc/crypto/EVP_SignInit.pod b/openssl/doc/crypto/EVP_SignInit.pod index b6e62ce7f..620a623ab 100644 --- a/openssl/doc/crypto/EVP_SignInit.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/EVP_VerifyInit.pod b/openssl/doc/crypto/EVP_VerifyInit.pod index b6afaedee..9097f0941 100644 --- a/openssl/doc/crypto/EVP_VerifyInit.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/OBJ_nid2obj.pod b/openssl/doc/crypto/OBJ_nid2obj.pod index 7dcc07923..1e45dd40f 100644 --- a/openssl/doc/crypto/OBJ_nid2obj.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod b/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod new file mode 100644 index 000000000..e070c45c2 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod b/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod new file mode 100644 index 000000000..16fc9b684 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PKCS12_parse.pod b/openssl/doc/crypto/PKCS12_parse.pod index 51344f883..c54cf2ad6 100644 --- a/openssl/doc/crypto/PKCS12_parse.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PKCS7_decrypt.pod b/openssl/doc/crypto/PKCS7_decrypt.pod index b0ca067b8..325699d0b 100644 --- a/openssl/doc/crypto/PKCS7_decrypt.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PKCS7_encrypt.pod b/openssl/doc/crypto/PKCS7_encrypt.pod index 1a507b22a..2cd925a7e 100644 --- a/openssl/doc/crypto/PKCS7_encrypt.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PKCS7_sign.pod b/openssl/doc/crypto/PKCS7_sign.pod index ffd0c734b..64a35144f 100644 --- a/openssl/doc/crypto/PKCS7_sign.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PKCS7_sign_add_signer.pod b/openssl/doc/crypto/PKCS7_sign_add_signer.pod new file mode 100644 index 000000000..ebec4d57d --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/PKCS7_verify.pod b/openssl/doc/crypto/PKCS7_verify.pod index 3490b5dc8..7c10a4cc3 100644 --- a/openssl/doc/crypto/PKCS7_verify.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/SMIME_read_CMS.pod b/openssl/doc/crypto/SMIME_read_CMS.pod new file mode 100644 index 000000000..acc5524c1 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/SMIME_read_PKCS7.pod b/openssl/doc/crypto/SMIME_read_PKCS7.pod index ffafa3788..9d4671594 100644 --- a/openssl/doc/crypto/SMIME_read_PKCS7.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/SMIME_write_CMS.pod b/openssl/doc/crypto/SMIME_write_CMS.pod new file mode 100644 index 000000000..04bedfb42 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/SMIME_write_PKCS7.pod b/openssl/doc/crypto/SMIME_write_PKCS7.pod index 61945b388..ca6bd0276 100644 --- a/openssl/doc/crypto/SMIME_write_PKCS7.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod b/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod index 11b35f6fd..41902c0d4 100644 --- a/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod b/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod index e2ab4b0d2..1afd008cb 100644 --- a/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod b/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod index 333323d73..3b1f9ff43 100644 --- a/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_STORE_CTX_get_error.pod b/openssl/doc/crypto/X509_STORE_CTX_get_error.pod new file mode 100644 index 000000000..a883f6c09 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod b/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod new file mode 100644 index 000000000..8d6b9dda4 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_STORE_CTX_new.pod b/openssl/doc/crypto/X509_STORE_CTX_new.pod new file mode 100644 index 000000000..b17888f14 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod new file mode 100644 index 000000000..b9787a6ca --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod b/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod new file mode 100644 index 000000000..29e3bbe3b --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod new file mode 100644 index 000000000..b68eece03 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_new.pod b/openssl/doc/crypto/X509_new.pod index fd5fc65ce..d38872335 100644 --- a/openssl/doc/crypto/X509_new.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/X509_verify_cert.pod b/openssl/doc/crypto/X509_verify_cert.pod new file mode 100644 index 000000000..5253bdcd7 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/bn_internal.pod b/openssl/doc/crypto/bn_internal.pod index 891914678..91840b0f0 100644 --- a/openssl/doc/crypto/bn_internal.pod +++ b/openssl/doc/crypto/bn_internal.pod @@ -13,6 +13,8 @@ library internal functions =head1 SYNOPSIS + #include + BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); @@ -70,24 +72,34 @@ applications. =head2 The BIGNUM structure - typedef struct bignum_st + typedef struct bignum_st BIGNUM; + + struct bignum_st { - int top; /* number of words used in d */ - BN_ULONG *d; /* pointer to an array containing the integer value */ - int max; /* size of the d array */ - int neg; /* sign */ - } BIGNUM; + BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ + int top; /* Index of last used d +1. */ + /* The next are internal book keeping for bn_expand. */ + int dmax; /* Size of the d array. */ + int neg; /* one if the number is negative */ + int flags; + }; + The integer value is stored in B, a malloc()ed array of words (B), least significant word first. A B can be either 16, 32 or 64 bits in size, depending on the 'number of bits' (B) specified in C. -B is the size of the B array that has been allocated. B +B is the size of the B array that has been allocated. B is the number of words being used, so for a value of 4, bn.d[0]=4 and bn.top=1. B is 1 if the number is negative. When a B is B<0>, the B field can be B and B == B<0>. +B is a bit field of flags which are defined in C. The +flags begin with B. The macros BN_set_flags(b,n) and +BN_get_flags(b,n) exist to enable or fetch flag(s) B from B +structure B. + Various routines in this library require the use of temporary B variables during their execution. Since dynamic memory allocation to create Bs is rather expensive when used in @@ -207,12 +219,12 @@ significant non-zero word plus one when B has shrunk. =head2 Debugging bn_check_top() verifies that C<((a)-Etop E= 0 && (a)-Etop -E= (a)-Emax)>. A violation will cause the program to abort. +E= (a)-Edmax)>. A violation will cause the program to abort. bn_print() prints B to stderr. bn_dump() prints B words at B (in reverse order, i.e. most significant word first) to stderr. -bn_set_max() makes B a static number with a B of its current size. +bn_set_max() makes B a static number with a B of its current size. This is used by bn_set_low() and bn_set_high() to make B a read-only B that contains the B low or high words of B. diff --git a/openssl/doc/crypto/d2i_RSAPublicKey.pod b/openssl/doc/crypto/d2i_RSAPublicKey.pod index 279b29c87..aa6078bcf 100644 --- a/openssl/doc/crypto/d2i_RSAPublicKey.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/d2i_X509.pod b/openssl/doc/crypto/d2i_X509.pod index 5bfa18afb..298ec54a4 100644 --- a/openssl/doc/crypto/d2i_X509.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/d2i_X509_CRL.pod b/openssl/doc/crypto/d2i_X509_CRL.pod index e7295a5d6..224f9e082 100644 --- a/openssl/doc/crypto/d2i_X509_CRL.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/d2i_X509_REQ.pod b/openssl/doc/crypto/d2i_X509_REQ.pod index ae32a3891..91c0c1974 100644 --- a/openssl/doc/crypto/d2i_X509_REQ.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/evp.pod b/openssl/doc/crypto/evp.pod index b3ca14314..9faa34924 100644 --- a/openssl/doc/crypto/evp.pod +++ b/openssl/doc/crypto/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/openssl/doc/crypto/hmac.pod b/openssl/doc/crypto/hmac.pod index 0bd79a6d3..d92138d27 100644 --- a/openssl/doc/crypto/hmac.pod +++ b/openssl/doc/crypto/hmac.pod @@ -15,12 +15,12 @@ authentication code void HMAC_CTX_init(HMAC_CTX *ctx); - void HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, + int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, const EVP_MD *md); - void HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, + int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, const EVP_MD *md, ENGINE *impl); - void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); - void HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); + int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); + int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); void HMAC_CTX_cleanup(HMAC_CTX *ctx); void HMAC_cleanup(HMAC_CTX *ctx); @@ -41,8 +41,6 @@ If B is NULL, the digest is placed in a static array. The size of the output is placed in B, unless it is B. B can be EVP_sha1(), EVP_ripemd160() etc. -B and B may be B if a key and hash function have -been set in a previous call to HMAC_Init() for that B. HMAC_CTX_init() initialises a B before first use. It must be called. @@ -78,10 +76,13 @@ must have space for the hash function output. =head1 RETURN VALUES -HMAC() returns a pointer to the message authentication code. +HMAC() returns a pointer to the message authentication code or NULL if +an error occurred. -HMAC_CTX_init(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and -HMAC_CTX_cleanup() do not return values. +HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if +an error occurred. + +HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. =head1 CONFORMING TO @@ -99,4 +100,7 @@ are available since SSLeay 0.9.0. HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available since OpenSSL 0.9.7. +HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in +versions of OpenSSL before 1.0.0. + =cut diff --git a/openssl/doc/crypto/i2d_CMS_bio_stream.pod b/openssl/doc/crypto/i2d_CMS_bio_stream.pod new file mode 100644 index 000000000..558bdd081 --- /dev/null +++ b/openssl/doc/crypto/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/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod b/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod new file mode 100644 index 000000000..dc4d884c5 --- /dev/null +++ b/openssl/doc/crypto/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 diff --git a/openssl/doc/crypto/lhash.pod b/openssl/doc/crypto/lhash.pod index dcdbb43a8..73a19b6c7 100644 --- a/openssl/doc/crypto/lhash.pod +++ b/openssl/doc/crypto/lhash.pod @@ -8,18 +8,20 @@ lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_e #include - LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare); - void lh_free(LHASH *table); + DECLARE_LHASH_OF(); - void *lh_insert(LHASH *table, void *data); - void *lh_delete(LHASH *table, void *data); - void *lh_retrieve(LHASH *table, void *data); + LHASH *lh__new(); + void lh__free(LHASH_OF( *table); - void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func); - void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func, - void *arg); + *lh__insert(LHASH_OF( *table, *data); + *lh__delete(LHASH_OF( *table, *data); + *lh_retrieve(LHASH_OF *table, *data); - int lh_error(LHASH *table); + void lh__doall(LHASH_OF( *table, LHASH_DOALL_FN_TYPE func); + void lh__doall_arg(LHASH_OF( *table, LHASH_DOALL_ARG_FN_TYPE func, + , *arg); + + int lh__error(LHASH_OF( *table); typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); @@ -28,113 +30,115 @@ lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_e =head1 DESCRIPTION -This library implements dynamic hash tables. The hash table entries -can be arbitrary structures. Usually they consist of key and value -fields. - -lh_new() creates a new B structure to store arbitrary data -entries, and provides the 'hash' and 'compare' callbacks to be used in -organising the table's entries. The B callback takes a pointer -to a table entry as its argument and returns an unsigned long hash -value for its key field. The hash value is normally truncated to a -power of 2, so make sure that your hash function returns well mixed -low order bits. The B callback takes two arguments (pointers -to two hash table entries), and returns 0 if their keys are equal, -non-zero otherwise. If your hash table will contain items of some -particular type and the B and B callbacks hash/compare -these types, then the B and -B macros can be used to create callback -wrappers of the prototypes required by lh_new(). These provide -per-variable casts before calling the type-specific callbacks written -by the application author. These macros, as well as those used for -the "doall" callbacks, are defined as; - - #define DECLARE_LHASH_HASH_FN(f_name,o_type) \ - unsigned long f_name##_LHASH_HASH(const void *); - #define IMPLEMENT_LHASH_HASH_FN(f_name,o_type) \ - unsigned long f_name##_LHASH_HASH(const void *arg) { \ - o_type a = (o_type)arg; \ - return f_name(a); } - #define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH - - #define DECLARE_LHASH_COMP_FN(f_name,o_type) \ - int f_name##_LHASH_COMP(const void *, const void *); - #define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \ - int f_name##_LHASH_COMP(const void *arg1, const void *arg2) { \ - o_type a = (o_type)arg1; \ - o_type b = (o_type)arg2; \ - return f_name(a,b); } - #define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP - - #define DECLARE_LHASH_DOALL_FN(f_name,o_type) \ - void f_name##_LHASH_DOALL(const void *); - #define IMPLEMENT_LHASH_DOALL_FN(f_name,o_type) \ - void f_name##_LHASH_DOALL(const void *arg) { \ - o_type a = (o_type)arg; \ - f_name(a); } - #define LHASH_DOALL_FN(f_name) f_name##_LHASH_DOALL - - #define DECLARE_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \ - void f_name##_LHASH_DOALL_ARG(const void *, const void *); - #define IMPLEMENT_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \ - void f_name##_LHASH_DOALL_ARG(const void *arg1, const void *arg2) { \ - o_type a = (o_type)arg1; \ - a_type b = (a_type)arg2; \ - f_name(a,b); } - #define LHASH_DOALL_ARG_FN(f_name) f_name##_LHASH_DOALL_ARG - -An example of a hash table storing (pointers to) structures of type 'STUFF' -could be defined as follows; +This library implements type-checked dynamic hash tables. The hash +table entries can be arbitrary structures. Usually they consist of key +and value fields. + +lh__new() creates a new B> structure to store +arbitrary data entries, and provides the 'hash' and 'compare' +callbacks to be used in organising the table's entries. The B +callback takes a pointer to a table entry as its argument and returns +an unsigned long hash value for its key field. The hash value is +normally truncated to a power of 2, so make sure that your hash +function returns well mixed low order bits. The B callback +takes two arguments (pointers to two hash table entries), and returns +0 if their keys are equal, non-zero otherwise. If your hash table +will contain items of some particular type and the B and +B callbacks hash/compare these types, then the +B and B macros can be +used to create callback wrappers of the prototypes required by +lh__new(). These provide per-variable casts before calling the +type-specific callbacks written by the application author. These +macros, as well as those used for the "doall" callbacks, are defined +as; + + #define DECLARE_LHASH_HASH_FN(name, o_type) \ + unsigned long name##_LHASH_HASH(const void *); + #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \ + unsigned long name##_LHASH_HASH(const void *arg) { \ + const o_type *a = arg; \ + return name##_hash(a); } + #define LHASH_HASH_FN(name) name##_LHASH_HASH + + #define DECLARE_LHASH_COMP_FN(name, o_type) \ + int name##_LHASH_COMP(const void *, const void *); + #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \ + int name##_LHASH_COMP(const void *arg1, const void *arg2) { \ + const o_type *a = arg1; \ + const o_type *b = arg2; \ + return name##_cmp(a,b); } + #define LHASH_COMP_FN(name) name##_LHASH_COMP + + #define DECLARE_LHASH_DOALL_FN(name, o_type) \ + void name##_LHASH_DOALL(void *); + #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \ + void name##_LHASH_DOALL(void *arg) { \ + o_type *a = arg; \ + name##_doall(a); } + #define LHASH_DOALL_FN(name) name##_LHASH_DOALL + + #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ + void name##_LHASH_DOALL_ARG(void *, void *); + #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ + void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \ + o_type *a = arg1; \ + a_type *b = arg2; \ + name##_doall_arg(a, b); } + #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG + + An example of a hash table storing (pointers to) structures of type 'STUFF' + could be defined as follows; /* Calculates the hash value of 'tohash' (implemented elsewhere) */ unsigned long STUFF_hash(const STUFF *tohash); /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ - int STUFF_cmp(const STUFF *arg1, const STUFF *arg2); + int stuff_cmp(const STUFF *arg1, const STUFF *arg2); /* Create the type-safe wrapper functions for use in the LHASH internals */ - static IMPLEMENT_LHASH_HASH_FN(STUFF_hash, const STUFF *) - static IMPLEMENT_LHASH_COMP_FN(STUFF_cmp, const STUFF *); + static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); + static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); /* ... */ int main(int argc, char *argv[]) { /* Create the new hash table using the hash/compare wrappers */ - LHASH *hashtable = lh_new(LHASH_HASH_FN(STUFF_hash), + LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), LHASH_COMP_FN(STUFF_cmp)); /* ... */ } -lh_free() frees the B structure B. Allocated hash table -entries will not be freed; consider using lh_doall() to deallocate any -remaining entries in the hash table (see below). +lh__free() frees the B> structure +B
. Allocated hash table entries will not be freed; consider +using lh__doall() to deallocate any remaining entries in the +hash table (see below). -lh_insert() inserts the structure pointed to by B into B
. -If there already is an entry with the same key, the old value is -replaced. Note that lh_insert() stores pointers, the data are not -copied. +lh__insert() inserts the structure pointed to by B into +B
. If there already is an entry with the same key, the old +value is replaced. Note that lh__insert() stores pointers, the +data are not copied. -lh_delete() deletes an entry from B
. +lh__delete() deletes an entry from B
. -lh_retrieve() looks up an entry in B
. Normally, B is -a structure with the key field(s) set; the function will return a +lh__retrieve() looks up an entry in B
. Normally, B +is a structure with the key field(s) set; the function will return a pointer to a fully populated structure. -lh_doall() will, for every entry in the hash table, call B with -the data item as its parameter. For lh_doall() and lh_doall_arg(), -function pointer casting should be avoided in the callbacks (see -B) - instead, either declare the callbacks to match the -prototype required in lh_new() or use the declare/implement macros to -create type-safe wrappers that cast variables prior to calling your -type-specific callbacks. An example of this is illustrated here where -the callback is used to cleanup resources for items in the hash table -prior to the hashtable itself being deallocated: +lh__doall() will, for every entry in the hash table, call +B with the data item as its parameter. For lh__doall() +and lh__doall_arg(), function pointer casting should be avoided +in the callbacks (see B) - instead use the declare/implement +macros to create type-checked wrappers that cast variables prior to +calling your type-specific callbacks. An example of this is +illustrated here where the callback is used to cleanup resources for +items in the hash table prior to the hashtable itself being +deallocated: /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ - void STUFF_cleanup(STUFF *a); + void STUFF_cleanup_doall(STUFF *a); /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ - IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF *) + IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) /* ... then later in the code ... */ /* So to run "STUFF_cleanup" against all items in a hash table ... */ - lh_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); + lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); /* Then the hash table itself can be deallocated */ - lh_free(hashtable); + lh_STUFF_free(hashtable); When doing this, be careful if you delete entries from the hash table in your callbacks: the table may decrease in size, moving the item @@ -145,51 +149,52 @@ you start (which will stop the hash table ever decreasing in size). The best solution is probably to avoid deleting items from the hash table inside a "doall" callback! -lh_doall_arg() is the same as lh_doall() except that B will be -called with B as the second argument and B should be of -type B (a callback prototype that is passed -both the table entry and an extra argument). As with lh_doall(), you -can instead choose to declare your callback with a prototype matching -the types you are dealing with and use the declare/implement macros to -create compatible wrappers that cast variables before calling your -type-specific callbacks. An example of this is demonstrated here -(printing all hash table entries to a BIO that is provided by the -caller): +lh__doall_arg() is the same as lh__doall() except that +B will be called with B as the second argument and B +should be of type B (a callback prototype +that is passed both the table entry and an extra argument). As with +lh_doall(), you can instead choose to declare your callback with a +prototype matching the types you are dealing with and use the +declare/implement macros to create compatible wrappers that cast +variables before calling your type-specific callbacks. An example of +this is demonstrated here (printing all hash table entries to a BIO +that is provided by the caller): /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ - void STUFF_print(const STUFF *a, BIO *output_bio); + void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); /* Implement a prototype-compatible wrapper for "STUFF_print" */ - static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF_print, const STUFF *, BIO *) + static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) /* ... then later in the code ... */ /* Print out the entire hashtable to a particular BIO */ - lh_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), logging_bio); + lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, + logging_bio); -lh_error() can be used to determine if an error occurred in the last -operation. lh_error() is a macro. +lh__error() can be used to determine if an error occurred in the last +operation. lh__error() is a macro. =head1 RETURN VALUES -lh_new() returns B on error, otherwise a pointer to the new +lh__new() returns B on error, otherwise a pointer to the new B structure. -When a hash table entry is replaced, lh_insert() returns the value +When a hash table entry is replaced, lh__insert() returns the value being replaced. B is returned on normal operation and on error. -lh_delete() returns the entry being deleted. B is returned if +lh__delete() returns the entry being deleted. B is returned if there is no such value in the hash table. -lh_retrieve() returns the hash table entry if it has been found, +lh__retrieve() returns the hash table entry if it has been found, B otherwise. -lh_error() returns 1 if an error occurred in the last operation, 0 +lh__error() returns 1 if an error occurred in the last operation, 0 otherwise. -lh_free(), lh_doall() and lh_doall_arg() return no values. +lh__free(), lh__doall() and lh__doall_arg() return no values. =head1 NOTE The various LHASH macros and callback types exist to make it possible -to write type-safe code without resorting to function-prototype +to write type-checked code without resorting to function-prototype casting - an evil that makes application code much harder to audit/verify and also opens the window of opportunity for stack corruption and other hard-to-find bugs. It also, apparently, violates @@ -227,7 +232,7 @@ without any "const" qualifiers. =head1 BUGS -lh_insert() returns B both for success and error. +lh__insert() returns B both for success and error. =head1 INTERNALS @@ -272,8 +277,8 @@ lh_strhash() is a demo string hashing function: unsigned long lh_strhash(const char *c); Since the B routines would normally be passed structures, this -routine would not normally be passed to lh_new(), rather it would be -used in the function passed to lh_new(). +routine would not normally be passed to lh__new(), rather it would be +used in the function passed to lh__new(). =head1 SEE ALSO @@ -291,4 +296,7 @@ were changed for better type safety, and the function types LHASH_COMP_FN_TYPE, LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE became available. +In OpenSSL 1.0.0, the lhash interface was revamped for even better +type checking. + =cut diff --git a/openssl/doc/crypto/pem.pod b/openssl/doc/crypto/pem.pod index 4f9a27df0..d5b189611 100644 --- a/openssl/doc/crypto/pem.pod +++ b/openssl/doc/crypto/pem.pod @@ -2,7 +2,7 @@ =head1 NAME -PEM - PEM routines +PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines =head1 SYNOPSIS diff --git a/openssl/doc/crypto/threads.pod b/openssl/doc/crypto/threads.pod index 3df4ecd77..dc0e9391d 100644 --- a/openssl/doc/crypto/threads.pod +++ b/openssl/doc/crypto/threads.pod @@ -2,7 +2,9 @@ =head1 NAME -CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks, +CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, +CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, +CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support @@ -11,14 +13,26 @@ CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support #include - void CRYPTO_set_locking_callback(void (*locking_function)(int mode, - int n, const char *file, int line)); - - void CRYPTO_set_id_callback(unsigned long (*id_function)(void)); + /* Don't use this structure directly. */ + typedef struct crypto_threadid_st + { + void *ptr; + unsigned long val; + } CRYPTO_THREADID; + /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ + void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); + void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); + int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); + void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); + void CRYPTO_THREADID_current(CRYPTO_THREADID *id); + int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, + const CRYPTO_THREADID *b); + void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, + const CRYPTO_THREADID *src); + unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); int CRYPTO_num_locks(void); - /* struct CRYPTO_dynlock_value needs to be defined by the user */ struct CRYPTO_dynlock_value; @@ -50,7 +64,8 @@ CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support =head1 DESCRIPTION OpenSSL can safely be used in multi-threaded applications provided -that at least two callback functions are set. +that at least two callback functions are set, locking_function and +threadid_func. locking_function(int mode, int n, const char *file, int line) is needed to perform locking on shared data structures. @@ -65,10 +80,42 @@ B, and releases it otherwise. B and B are the file number of the function setting the lock. They can be useful for debugging. -id_function(void) is a function that returns a thread ID, for example -pthread_self() if it returns an integer (see NOTES below). It isn't -needed on Windows nor on platforms where getpid() returns a different -ID for each thread (see NOTES below). +threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing +thread's identifier into B. The implementation of this callback should not +fill in B directly, but should use CRYPTO_THREADID_set_numeric() if thread +IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. +If the application does not register such a callback using +CRYPTO_THREADID_set_callback(), then a default implementation is used - on +Windows and BeOS this uses the system's default thread identifying APIs, and on +all other platforms it uses the address of B. The latter is satisfactory +for thread-safety if and only if the platform has a thread-local error number +facility. + +Once threadid_func() is registered, or if the built-in default implementation is +to be used; + +=over 4 + +=item * +CRYPTO_THREADID_current() records the currently-executing thread ID into the +given B object. + +=item * +CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. +the same semantics as memcmp()). + +=item * +CRYPTO_THREADID_cpy() duplicates a thread ID value, + +=item * +CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This +is usually the exact numeric or pointer-based thread ID used internally, however +this also handles the unusual case where pointers are larger than 'long' +variables and the platform's thread IDs are pointer-based - in this case, mixing +is done to attempt to produce a unique numeric value even though it is not as +wide as the platform's true thread IDs. + +=back Additionally, OpenSSL supports dynamic locks, and sometimes, some parts of OpenSSL need it for better performance. To enable this, the following @@ -140,22 +187,6 @@ You can find out if OpenSSL was configured with thread support: Also, dynamic locks are currently not used internally by OpenSSL, but may do so in the future. -Defining id_function(void) has it's own issues. Generally speaking, -pthread_self() should be used, even on platforms where getpid() gives -different answers in each thread, since that may depend on the machine -the program is run on, not the machine where the program is being -compiled. For instance, Red Hat 8 Linux and earlier used -LinuxThreads, whose getpid() returns a different value for each -thread. Red Hat 9 Linux and later use NPTL, which is -Posix-conformant, and has a getpid() that returns the same value for -all threads in a process. A program compiled on Red Hat 8 and run on -Red Hat 9 will therefore see getpid() returning the same value for -all threads. - -There is still the issue of platforms where pthread_self() returns -something other than an integer. This is a bit unusual, and this -manual has no cookbook solution for that case. - =head1 EXAMPLES B shows examples of the callback functions on @@ -163,10 +194,14 @@ Solaris, Irix and Win32. =head1 HISTORY -CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are +CRYPTO_set_locking_callback() is available in all versions of SSLeay and OpenSSL. CRYPTO_num_locks() was added in OpenSSL 0.9.4. All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. +B and associated functions were introduced in OpenSSL 1.0.0 +to replace (actually, deprecate) the previous CRYPTO_set_id_callback(), +CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed +thread IDs to always be represented by 'unsigned long'. =head1 SEE ALSO diff --git a/openssl/doc/crypto/ui_compat.pod b/openssl/doc/crypto/ui_compat.pod index 9ab3c69bf..adf2ae5e5 100644 --- a/openssl/doc/crypto/ui_compat.pod +++ b/openssl/doc/crypto/ui_compat.pod @@ -7,6 +7,8 @@ Compatibility user interface functions =head1 SYNOPSIS + #include + int des_read_password(DES_cblock *key,const char *prompt,int verify); int des_read_2passwords(DES_cblock *key1,DES_cblock *key2, const char *prompt,int verify); -- cgit v1.2.3