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/apps/asn1parse.pod | 14 +- openssl/doc/apps/ca.pod | 12 +- openssl/doc/apps/ciphers.pod | 58 +- openssl/doc/apps/cms.pod | 602 +++++++++++++++++++++ openssl/doc/apps/dgst.pod | 47 ++ openssl/doc/apps/dhparam.pod | 2 +- openssl/doc/apps/dsa.pod | 2 +- openssl/doc/apps/dsaparam.pod | 2 +- openssl/doc/apps/ec.pod | 2 +- openssl/doc/apps/ecparam.pod | 2 +- openssl/doc/apps/enc.pod | 70 ++- openssl/doc/apps/gendsa.pod | 2 +- openssl/doc/apps/genpkey.pod | 213 ++++++++ openssl/doc/apps/genrsa.pod | 2 +- openssl/doc/apps/ocsp.pod | 6 + openssl/doc/apps/openssl.pod | 93 +++- openssl/doc/apps/pkcs12.pod | 85 ++- openssl/doc/apps/pkcs7.pod | 2 +- openssl/doc/apps/pkcs8.pod | 2 +- openssl/doc/apps/pkey.pod | 135 +++++ openssl/doc/apps/pkeyparam.pod | 69 +++ openssl/doc/apps/pkeyutl.pod | 222 ++++++++ openssl/doc/apps/req.pod | 91 +++- openssl/doc/apps/rsa.pod | 2 +- openssl/doc/apps/s_client.pod | 27 +- openssl/doc/apps/s_server.pod | 15 +- openssl/doc/apps/smime.pod | 118 +++- openssl/doc/apps/speed.pod | 2 +- openssl/doc/apps/spkac.pod | 2 +- openssl/doc/apps/ts.pod | 594 ++++++++++++++++++++ openssl/doc/apps/tsget.pod | 194 +++++++ openssl/doc/apps/verify.pod | 100 +++- openssl/doc/apps/x509.pod | 30 +- openssl/doc/apps/x509v3_config.pod | 97 +++- 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 + openssl/doc/ssl/SSL_CIPHER_get_name.pod | 2 +- openssl/doc/ssl/SSL_CTX_new.pod | 2 +- openssl/doc/ssl/SSL_CTX_set_mode.pod | 10 + openssl/doc/ssl/SSL_CTX_set_options.pod | 123 ++++- .../doc/ssl/SSL_CTX_set_psk_client_callback.pod | 81 +++ openssl/doc/ssl/SSL_CTX_set_ssl_version.pod | 6 +- openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod | 102 ++++ openssl/doc/ssl/SSL_get_psk_identity.pod | 63 +++ openssl/doc/ssl/SSL_library_init.pod | 1 + openssl/doc/ssl/ssl.pod | 50 +- openssl/doc/ssleay.txt | 26 +- openssl/doc/standards.txt | 4 + 127 files changed, 7499 insertions(+), 520 deletions(-) create mode 100644 openssl/doc/apps/cms.pod create mode 100644 openssl/doc/apps/genpkey.pod create mode 100644 openssl/doc/apps/pkey.pod create mode 100644 openssl/doc/apps/pkeyparam.pod create mode 100644 openssl/doc/apps/pkeyutl.pod create mode 100644 openssl/doc/apps/ts.pod create mode 100644 openssl/doc/apps/tsget.pod 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 create mode 100644 openssl/doc/ssl/SSL_CTX_set_psk_client_callback.pod create mode 100644 openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod create mode 100644 openssl/doc/ssl/SSL_get_psk_identity.pod (limited to 'openssl/doc') diff --git a/openssl/doc/apps/asn1parse.pod b/openssl/doc/apps/asn1parse.pod index 542d96906..f7bb92621 100644 --- a/openssl/doc/apps/asn1parse.pod +++ b/openssl/doc/apps/asn1parse.pod @@ -72,11 +72,11 @@ option can be used multiple times to "drill down" into a nested structure. =item B<-genstr string>, B<-genconf file> generate encoded data based on B, B or both using -ASN1_generate_nconf() format. If B only is present then the string -is obtained from the default section using the name B. The encoded -data is passed through the ASN1 parser and printed out as though it came -from a file, the contents can thus be examined and written to a file -using the B option. +L format. If B only is +present then the string is obtained from the default section using the name +B. The encoded data is passed through the ASN1 parser and printed out as +though it came from a file, the contents can thus be examined and written to a +file using the B option. =back @@ -168,4 +168,8 @@ Example config file: There should be options to change the format of output lines. The output of some ASN.1 types is not well handled (if at all). +=head1 SEE ALSO + +L + =cut diff --git a/openssl/doc/apps/ca.pod b/openssl/doc/apps/ca.pod index 5618c2dc9..9ff0cc361 100644 --- a/openssl/doc/apps/ca.pod +++ b/openssl/doc/apps/ca.pod @@ -205,7 +205,9 @@ the section of the configuration file containing certificate extensions to be added when a certificate is issued (defaults to B unless the B<-extfile> option is used). If no extension section is present then, a V1 certificate is created. If the extension section -is present (even if it is empty), then a V3 certificate is created. +is present (even if it is empty), then a V3 certificate is created. See the:w +L manual page for details of the +extension section format. =item B<-extfile file> @@ -215,7 +217,7 @@ used). =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. @@ -299,7 +301,9 @@ include. If no CRL extension section is present then a V1 CRL is created, if the CRL extension section is present (even if it is empty) then a V2 CRL is created. The CRL extensions specified are CRL extensions and B CRL entry extensions. It should be noted -that some software (for example Netscape) can't handle V2 CRLs. +that some software (for example Netscape) can't handle V2 CRLs. See +L manual page for details of the +extension section format. =back @@ -666,6 +670,6 @@ then even if a certificate is issued with CA:TRUE it will not be valid. =head1 SEE ALSO L, L, L, L, -L +L, L =cut diff --git a/openssl/doc/apps/ciphers.pod b/openssl/doc/apps/ciphers.pod index 694e433ef..f44aa00a2 100644 --- a/openssl/doc/apps/ciphers.pod +++ b/openssl/doc/apps/ciphers.pod @@ -8,6 +8,7 @@ ciphers - SSL cipher display and cipher list tool. B B [B<-v>] +[B<-V>] [B<-ssl2>] [B<-ssl3>] [B<-tls1>] @@ -15,7 +16,7 @@ B B =head1 DESCRIPTION -The B command converts OpenSSL cipher lists into ordered +The B command converts textual OpenSSL cipher lists into ordered SSL cipher preference lists. It can be used as a test tool to determine the appropriate cipherlist. @@ -25,7 +26,7 @@ the appropriate cipherlist. =item B<-v> -verbose option. List ciphers with a complete description of +Verbose option. List ciphers with a complete description of protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange, authentication, encryption and mac algorithms used along with any key size restrictions and whether the algorithm is classed as an "export" cipher. @@ -33,6 +34,10 @@ Note that without the B<-v> option, ciphers may seem to appear twice in a cipher list; this is when similar ciphers are available for SSL v2 and for SSL v3/TLS v1. +=item B<-V> + +Like B<-V>, but include cipher suite codes in output (hex format). + =item B<-ssl3> only include SSL v3 ciphers. @@ -104,8 +109,8 @@ The following is a list of all permitted cipher strings and their meanings. =item B -the default cipher list. This is determined at compile time and is normally -B. This must be the first cipher string +the default cipher list. This is determined at compile time and, as of OpenSSL +1.0.0, is normally B. This must be the first cipher string specified. =item B @@ -116,7 +121,8 @@ not included by B (use B if necessary). =item B -all ciphers suites except the B ciphers which must be explicitly enabled. +all cipher suites except the B ciphers which must be explicitly enabled; +as of OpenSSL, the B cipher suites are reasonably ordered by default =item B @@ -245,6 +251,33 @@ cipher suites using MD5. cipher suites using SHA1. +=item B + +cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction +(needs an engine supporting GOST algorithms). + +=item B + +cipher suites using GOST R 34.10-2001 authentication. + +=item B + +cipher suites using GOST R 34.10-94 authentication (note that R 34.10-94 +standard has been expired so use GOST R 34.10-2001) + +=item B + +cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357. + +=item B + +cipher suites, using HMAC based on GOST R 34.11-94. + +=item B + +cipher suites using GOST 28147-89 MAC B HMAC. + + =back =head1 CIPHER SUITE NAMES @@ -370,6 +403,16 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used. TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA +=head2 GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0 + +Note: these ciphers require an engine which including GOST cryptographic +algorithms, such as the B engine, included in the OpenSSL distribution. + + TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89 + TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89 + TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94 + TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94 + =head2 Additional Export 1024 and other cipher suites Note: these ciphers can also be used in SSL v3. @@ -428,7 +471,8 @@ L, L, L =head1 HISTORY -The B and B selection options were -added in version 0.9.7. +The B and B selection options +for cipherlist strings were added in OpenSSL 0.9.7. +The B<-V> option for the B command was added in OpenSSL 1.0.0. =cut diff --git a/openssl/doc/apps/cms.pod b/openssl/doc/apps/cms.pod new file mode 100644 index 000000000..a09588a18 --- /dev/null +++ b/openssl/doc/apps/cms.pod @@ -0,0 +1,602 @@ +=pod + +=head1 NAME + +cms - CMS utility + +=head1 SYNOPSIS + +B B +[B<-encrypt>] +[B<-decrypt>] +[B<-sign>] +[B<-verify>] +[B<-cmsout>] +[B<-resign>] +[B<-data_create>] +[B<-data_out>] +[B<-digest_create>] +[B<-digest_verify>] +[B<-compress>] +[B<-uncompress>] +[B<-EncryptedData_encrypt>] +[B<-sign_receipt>] +[B<-verify_receipt receipt>] +[B<-in filename>] +[B<-inform SMIME|PEM|DER>] +[B<-rctform SMIME|PEM|DER>] +[B<-out filename>] +[B<-outform SMIME|PEM|DER>] +[B<-stream -indef -noindef>] +[B<-noindef>] +[B<-content filename>] +[B<-text>] +[B<-noout>] +[B<-print>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-md digest>] +[B<-[cipher]>] +[B<-nointern>] +[B<-no_signer_cert_verify>] +[B<-nocerts>] +[B<-noattr>] +[B<-nosmimecap>] +[B<-binary>] +[B<-nodetach>] +[B<-certfile file>] +[B<-certsout file>] +[B<-signer file>] +[B<-recip file>] +[B<-keyid>] +[B<-receipt_request_all -receipt_request_first>] +[B<-receipt_request_from emailaddress>] +[B<-receipt_request_to emailaddress>] +[B<-receipt_request_print>] +[B<-secretkey key>] +[B<-secretkeyid id>] +[B<-econtent_type type>] +[B<-inkey file>] +[B<-passin arg>] +[B<-rand file(s)>] +[B] +[B<-to addr>] +[B<-from addr>] +[B<-subject subj>] +[cert.pem]... + +=head1 DESCRIPTION + +The B command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and +verify, compress and uncompress S/MIME messages. + +=head1 COMMAND OPTIONS + +There are fourteen operation options that set the type of operation to be +performed. The meaning of the other options varies according to the operation +type. + +=over 4 + +=item B<-encrypt> + +encrypt mail for the given recipient certificates. Input file is the message +to be encrypted. The output file is the encrypted mail in MIME format. The +actual CMS type is EnvelopedData. + +=item B<-decrypt> + +decrypt mail using the supplied certificate and private key. Expects an +encrypted mail message in MIME format for the input file. The decrypted mail +is written to the output file. + +=item B<-sign> + +sign mail using the supplied certificate and private key. Input file is +the message to be signed. The signed message in MIME format is written +to the output file. + +=item B<-verify> + +verify signed mail. Expects a signed mail message on input and outputs +the signed data. Both clear text and opaque signing is supported. + +=item B<-cmsout> + +takes an input message and writes out a PEM encoded CMS structure. + +=item B<-resign> + +resign a message: take an existing message and one or more new signers. + +=item B<-data_create> + +Create a CMS B type. + +=item B<-data_out> + +B type and output the content. + +=item B<-digest_create> + +Create a CMS B type. + +=item B<-digest_verify> + +Verify a CMS B type and output the content. + +=item B<-compress> + +Create a CMS B type. OpenSSL must be compiled with B +support for this option to work, otherwise it will output an error. + +=item B<-uncompress> + +Uncompress a CMS B type and output the content. OpenSSL must be +compiled with B support for this option to work, otherwise it will +output an error. + +=item B<-EncryptedData_encrypt> + +Encrypt suppled content using supplied symmetric key and algorithm using a CMS +B type and output the content. + +=item B<-sign_receipt> + +Generate and output a signed receipt for the supplied message. The input +message B contain a signed receipt request. Functionality is otherwise +similar to the B<-sign> operation. + +=item B<-verify_receipt receipt> + +Verify a signed receipt in filename B. The input message B +contain the original receipt request. Functionality is otherwise similar +to the B<-verify> operation. + +=item B<-in filename> + +the input message to be encrypted or signed or the message to be decrypted +or verified. + +=item B<-inform SMIME|PEM|DER> + +this specifies the input format for the CMS structure. The default +is B which reads an S/MIME format message. B and B +format change this to expect PEM and DER format CMS structures +instead. This currently only affects the input format of the CMS +structure, if no CMS structure is being input (for example with +B<-encrypt> or B<-sign>) this option has no effect. + +=item B<-rctform SMIME|PEM|DER> + +specify the format for a signed receipt for use with the B<-receipt_verify> +operation. + +=item B<-out filename> + +the message text that has been decrypted or verified or the output MIME +format message that has been signed or verified. + +=item B<-outform SMIME|PEM|DER> + +this specifies the output format for the CMS structure. The default +is B which writes an S/MIME format message. B and B +format change this to write PEM and DER format CMS structures +instead. This currently only affects the output format of the CMS +structure, if no CMS structure is being output (for example with +B<-verify> or B<-decrypt>) this option has no effect. + +=item B<-stream -indef -noindef> + +the B<-stream> and B<-indef> options are equivalent and enable streaming I/O +for encoding operations. This permits single pass processing of data without +the need to hold the entire contents in memory, potentially supporting very +large files. Streaming is automatically set for S/MIME signing with detached +data if the output format is B it is currently off by default for all +other operations. + +=item B<-noindef> + +disable streaming I/O where it would produce and indefinite length constructed +encoding. This option currently has no effect. In future streaming will be +enabled by default on all relevant operations and this option will disable it. + +=item B<-content filename> + +This specifies a file containing the detached content, this is only +useful with the B<-verify> command. This is only usable if the CMS +structure is using the detached signature form where the content is +not included. This option will override any content if the input format +is S/MIME and it uses the multipart/signed MIME content type. + +=item B<-text> + +this option adds plain text (text/plain) MIME headers to the supplied +message if encrypting or signing. If decrypting or verifying it strips +off text headers: if the decrypted or verified message is not of MIME +type text/plain then an error occurs. + +=item B<-noout> + +for the B<-cmsout> operation do not output the parsed CMS structure. This +is useful when combined with the B<-print> option or if the syntax of the CMS +structure is being checked. + +=item B<-print> + +for the B<-cmsout> operation print out all fields of the CMS structure. This +is mainly useful for testing purposes. + +=item B<-CAfile file> + +a file containing trusted CA certificates, only used with B<-verify>. + +=item B<-CApath dir> + +a directory containing trusted CA certificates, only used with +B<-verify>. This directory must be a standard certificate directory: that +is a hash of each subject name (using B) should be linked +to each certificate. + +=item B<-md digest> + +digest algorithm to use when signing or resigning. If not present then the +default digest algorithm for the signing key will be used (usually SHA1). + +=item B<-[cipher]> + +the encryption algorithm to use. For example triple DES (168 bits) - B<-des3> +or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the +EVP_get_cipherbyname() function) can also be used preceded by a dash, for +example B<-aes_128_cbc>. See L|enc(1)> for a list of ciphers +supported by your version of OpenSSL. + +If not specified triple DES is used. Only used with B<-encrypt> and +B<-EncryptedData_create> commands. + +=item B<-nointern> + +when verifying a message normally certificates (if any) included in +the message are searched for the signing certificate. With this option +only the certificates specified in the B<-certfile> option are used. +The supplied certificates can still be used as untrusted CAs however. + +=item B<-no_signer_cert_verify> + +do not verify the signers certificate of a signed message. + +=item B<-nocerts> + +when signing a message the signer's certificate is normally included +with this option it is excluded. This will reduce the size of the +signed message but the verifier must have a copy of the signers certificate +available locally (passed using the B<-certfile> option for example). + +=item B<-noattr> + +normally when a message is signed a set of attributes are included which +include the signing time and supported symmetric algorithms. With this +option they are not included. + +=item B<-nosmimecap> + +exclude the list of supported algorithms from signed attributes, other options +such as signing time and content type are still included. + +=item B<-binary> + +normally the input message is converted to "canonical" format which is +effectively using CR and LF as end of line: as required by the S/MIME +specification. When this option is present no translation occurs. This +is useful when handling binary data which may not be in MIME format. + +=item B<-nodetach> + +when signing a message use opaque signing: this form is more resistant +to translation by mail relays but it cannot be read by mail agents that +do not support S/MIME. Without this option cleartext signing with +the MIME type multipart/signed is used. + +=item B<-certfile file> + +allows additional certificates to be specified. When signing these will +be included with the message. When verifying these will be searched for +the signers certificates. The certificates should be in PEM format. + +=item B<-certsout file> + +any certificates contained in the message are written to B. + +=item B<-signer file> + +a signing certificate when signing or resigning a message, this option can be +used multiple times if more than one signer is required. If a message is being +verified then the signers certificates will be written to this file if the +verification was successful. + +=item B<-recip file> + +the recipients certificate when decrypting a message. This certificate +must match one of the recipients of the message or an error occurs. + +=item B<-keyid> + +use subject key identifier to identify certificates instead of issuer name and +serial number. The supplied certificate B include a subject key +identifier extension. Supported by B<-sign> and B<-encrypt> options. + +=item B<-receipt_request_all -receipt_request_first> + +for B<-sign> option include a signed receipt request. Indicate requests should +be provided by all receipient or first tier recipients (those mailed directly +and not from a mailing list). Ignored it B<-receipt_request_from> is included. + +=item B<-receipt_request_from emailaddress> + +for B<-sign> option include a signed receipt request. Add an explicit email +address where receipts should be supplied. + +=item B<-receipt_request_to emailaddress> + +Add an explicit email address where signed receipts should be sent to. This +option B but supplied if a signed receipt it requested. + +=item B<-receipt_request_print> + +For the B<-verify> operation print out the contents of any signed receipt +requests. + +=item B<-secretkey key> + +specify symmetric key to use. The key must be supplied in hex format and be +consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt> +B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used +with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the +content encryption key using an AES key in the B type. + +=item B<-secretkeyid id> + +the key identifier for the supplied symmetric key for B type. +This option B be present if the B<-secretkey> option is used with +B<-encrypt>. With B<-decrypt> operations the B is used to locate the +relevant key if it is not supplied then an attempt is used to decrypt any +B structures. + +=item B<-econtent_type type> + +set the encapsulated content type to B if not supplied the B type +is used. The B argument can be any valid OID name in either text or +numerical format. + +=item B<-inkey file> + +the private key to use when signing or decrypting. This must match the +corresponding certificate. If this option is not specified then the +private key must be included in the certificate file specified with +the B<-recip> or B<-signer> file. When signing this option can be used +multiple times to specify successive keys. + +=item B<-passin arg> + +the private key password source. For more information about the format of B +see the B section in L. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L). +Multiple files can be specified separated by a OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B + +one or more certificates of message recipients: used when encrypting +a message. + +=item B<-to, -from, -subject> + +the relevant mail headers. These are included outside the signed +portion of a message so they may be included manually. If signing +then many S/MIME mail clients check the signers certificate's email +address matches that specified in the From: address. + +=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig> + +Set various certificate chain valiadition option. See the +L|verify(1)> manual page for details. + +=back + +=head1 NOTES + +The MIME message must be sent without any blank lines between the +headers and the output. Some mail programs will automatically add +a blank line. Piping the mail directly to sendmail is one way to +achieve the correct format. + +The supplied message to be signed or encrypted must include the +necessary MIME headers or many S/MIME clients wont display it +properly (if at all). You can use the B<-text> option to automatically +add plain text headers. + +A "signed and encrypted" message is one where a signed message is +then encrypted. This can be produced by encrypting an already signed +message: see the examples section. + +This version of the program only allows one signer per message but it +will verify multiple signers on received messages. Some S/MIME clients +choke if a message contains multiple signers. It is possible to sign +messages "in parallel" by signing an already signed message. + +The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME +clients. Strictly speaking these process CMS enveloped data: CMS +encrypted data is used for other purposes. + +The B<-resign> option uses an existing message digest when adding a new +signer. This means that attributes must be present in at least one existing +signer using the same message digest or this operation will fail. + +The B<-stream> and B<-indef> options enable experimental streaming I/O support. +As a result the encoding is BER using indefinite length constructed encoding +and no longer DER. Streaming is supported for the B<-encrypt> operation and the +B<-sign> operation if the content is not detached. + +Streaming is always used for the B<-sign> operation with detached data but +since the content is no longer part of the CMS structure the encoding +remains DER. + +=head1 EXIT CODES + +=over 4 + +=item 0 + +the operation was completely successfully. + +=item 1 + +an error occurred parsing the command options. + +=item 2 + +one of the input files could not be read. + +=item 3 + +an error occurred creating the CMS file or when reading the MIME +message. + +=item 4 + +an error occurred decrypting or verifying the message. + +=item 5 + +the message was verified correctly but an error occurred writing out +the signers certificates. + +=back + +=head1 COMPATIBILITY WITH PKCS#7 format. + +The B utility can only process the older B format. The B +utility supports Cryptographic Message Syntax format. Use of some features +will result in messages which cannot be processed by applications which only +support the older format. These are detailed below. + +The use of the B<-keyid> option with B<-sign> or B<-encrypt>. + +The B<-outform PEM> option uses different headers. + +The B<-compress> option. + +The B<-secretkey> option when used with B<-encrypt>. + +Additionally the B<-EncryptedData_create> and B<-data_create> type cannot +be processed by the older B command. + +=head1 EXAMPLES + +Create a cleartext signed message: + + openssl cms -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem + +Create an opaque signed message + + openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ + -signer mycert.pem + +Create a signed message, include some additional certificates and +read the private key from another file: + + openssl cms -sign -in in.txt -text -out mail.msg \ + -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem + +Create a signed message with two signers, use key identifier: + + openssl cms -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem -signer othercert.pem -keyid + +Send a signed message under Unix directly to sendmail, including headers: + + openssl cms -sign -in in.txt -text -signer mycert.pem \ + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed message" | sendmail someone@somewhere + +Verify a message and extract the signer's certificate if successful: + + openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt + +Send encrypted mail using triple DES: + + openssl cms -encrypt -in in.txt -from steve@openssl.org \ + -to someone@somewhere -subject "Encrypted message" \ + -des3 user.pem -out mail.msg + +Sign and encrypt mail: + + openssl cms -sign -in ml.txt -signer my.pem -text \ + | openssl cms -encrypt -out mail.msg \ + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed and Encrypted message" -des3 user.pem + +Note: the encryption command does not include the B<-text> option because the +message being encrypted already has MIME headers. + +Decrypt mail: + + openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem + +The output from Netscape form signing is a PKCS#7 structure with the +detached signature format. You can use this program to verify the +signature by line wrapping the base64 encoded structure and surrounding +it with: + + -----BEGIN PKCS7----- + -----END PKCS7----- + +and using the command, + + openssl cms -verify -inform PEM -in signature.pem -content content.txt + +alternatively you can base64 decode the signature and use + + openssl cms -verify -inform DER -in signature.der -content content.txt + +Create an encrypted message using 128 bit Camellia: + + openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem + +Add a signer to an existing message: + + openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg + +=head1 BUGS + +The MIME parser isn't very clever: it seems to handle most messages that I've +thrown at it but it may choke on others. + +The code currently will only write out the signer's certificate to a file: if +the signer has a separate encryption certificate this must be manually +extracted. There should be some heuristic that determines the correct +encryption certificate. + +Ideally a database should be maintained of a certificates for each email +address. + +The code doesn't currently take note of the permitted symmetric encryption +algorithms as supplied in the SMIMECapabilities signed attribute. this means the +user has to manually include the correct encryption algorithm. It should store +the list of permitted ciphers in a database and only use those. + +No revocation checking is done on the signer's certificate. + +=head1 HISTORY + +The use of multiple B<-signer> options and the B<-resign> command were first +added in OpenSSL 1.0.0 + + +=cut diff --git a/openssl/doc/apps/dgst.pod b/openssl/doc/apps/dgst.pod index 908cd2a6d..b035edf08 100644 --- a/openssl/doc/apps/dgst.pod +++ b/openssl/doc/apps/dgst.pod @@ -14,6 +14,7 @@ B B [B<-binary>] [B<-out filename>] [B<-sign filename>] +[B<-keyform arg>] [B<-passin arg>] [B<-verify filename>] [B<-prverify filename>] @@ -61,6 +62,23 @@ filename to output to, or standard output by default. digitally sign the digest using the private key in "filename". +=item B<-keyform arg> + +Specifies the key format to sign digest with. Only PEM and ENGINE +formats are supported by the B command. + +=item B<-engine id> + +Use engine B for operations (including private key storage). +This engine is not used as source for digest algorithms, unless it is +also specified in the configuration file. + +=item B<-sigopt nm:v> + +Pass options to the signature algorithm during sign or verify operations. +Names and values of these options are algorithm-specific. + + =item B<-passin arg> the private key password source. For more information about the format of B @@ -83,6 +101,35 @@ the actual signature to verify. create a hashed MAC using "key". +=item B<-mac alg> + +create MAC (keyed Message Authentication Code). The most popular MAC +algorithm is HMAC (hash-based MAC), but there are other MAC algorithms +which are not based on hash, for instance B algorithm, +supported by B engine. MAC keys and other options should be set +via B<-macopt> parameter. + +=item B<-macopt nm:v> + +Passes options to MAC algorithm, specified by B<-mac> key. +Following options are supported by both by B and B: + +=over 8 + +=item B + +Specifies MAC key as alphnumeric string (use if key contain printable +characters only). String length must conform to any restrictions of +the MAC algorithm for example exactly 32 chars for gost-mac. + +=item B + +Specifies MAC key in hexadecimal form (two hex digits per byte). +Key length must conform to any restrictions of the MAC algorithm +for example exactly 32 chars for gost-mac. + +=back + =item B<-rand file(s)> a file or files containing random data used to seed the random number diff --git a/openssl/doc/apps/dhparam.pod b/openssl/doc/apps/dhparam.pod index c31db95a4..9edb4ff4e 100644 --- a/openssl/doc/apps/dhparam.pod +++ b/openssl/doc/apps/dhparam.pod @@ -99,7 +99,7 @@ be loaded by calling the BIB<()> function. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/dsa.pod b/openssl/doc/apps/dsa.pod index ed06b8806..ddbc9327f 100644 --- a/openssl/doc/apps/dsa.pod +++ b/openssl/doc/apps/dsa.pod @@ -109,7 +109,7 @@ a public key. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/dsaparam.pod b/openssl/doc/apps/dsaparam.pod index b9b1b93b4..ba5ec4d72 100644 --- a/openssl/doc/apps/dsaparam.pod +++ b/openssl/doc/apps/dsaparam.pod @@ -85,7 +85,7 @@ the input file (if any) is ignored. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/ec.pod b/openssl/doc/apps/ec.pod index 1d4a36dbf..ba6dc4689 100644 --- a/openssl/doc/apps/ec.pod +++ b/openssl/doc/apps/ec.pod @@ -130,7 +130,7 @@ is currently not implemented in OpenSSL. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/ecparam.pod b/openssl/doc/apps/ecparam.pod index 1a12105da..788c074d7 100644 --- a/openssl/doc/apps/ecparam.pod +++ b/openssl/doc/apps/ecparam.pod @@ -121,7 +121,7 @@ all others. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/enc.pod b/openssl/doc/apps/enc.pod index 4391c9336..3dee4ed99 100644 --- a/openssl/doc/apps/enc.pod +++ b/openssl/doc/apps/enc.pod @@ -12,17 +12,24 @@ B [B<-pass arg>] [B<-e>] [B<-d>] -[B<-a>] +[B<-a/-base64>] [B<-A>] [B<-k password>] [B<-kfile filename>] [B<-K key>] [B<-iv IV>] +[B<-S salt>] +[B<-salt>] +[B<-nosalt>] +[B<-z>] +[B<-md>] [B<-p>] [B<-P>] [B<-bufsize number>] [B<-nopad>] [B<-debug>] +[B<-none>] +[B<-engine id>] =head1 DESCRIPTION @@ -50,15 +57,13 @@ see the B section in L. =item B<-salt> -use a salt in the key derivation routines. This option should B -be used unless compatibility with previous versions of OpenSSL or SSLeay -is required. This option is only present on OpenSSL versions 0.9.5 or -above. +use a salt in the key derivation routines. This is the default. =item B<-nosalt> -don't use a salt in the key derivation routines. This is the default for -compatibility with previous versions of OpenSSL and SSLeay. +don't use a salt in the key derivation routines. This option B be +used except for test purposes or compatibility with ancient versions of OpenSSL +and SSLeay. =item B<-e> @@ -74,6 +79,10 @@ base64 process the data. This means that if encryption is taking place the data is base64 encoded after encryption. If decryption is set then the input data is base64 decoded before being decrypted. +=item B<-base64> + +same as B<-a> + =item B<-A> if the B<-a> option is set then base64 process the data on one line. @@ -89,10 +98,18 @@ read the password to derive the key from the first line of B. This is for compatibility with previous versions of OpenSSL. Superseded by the B<-pass> argument. +=item B<-nosalt> + +do not use a salt + +=item B<-salt> + +use salt (randomly generated or provide with B<-S> option) when +encrypting (this is the default). + =item B<-S salt> -the actual salt to use: this must be represented as a string comprised only -of hex digits. +the actual salt to use: this must be represented as a string of hex digits. =item B<-K key> @@ -131,12 +148,34 @@ disable standard block padding debug the BIOs used for I/O. +=item B<-z> + +Compress or decompress clear text using zlib before encryption or after +decryption. This option exists only if OpenSSL with compiled with zlib +or zlib-dynamic option. + +=item B<-none> + +Use NULL cipher (no encryption or decryption of input). + =back =head1 NOTES The program can be called either as B or -B. +B. But the first form doesn't work with +engine-provided ciphers, because this form is processed before the +configuration file is read and any ENGINEs loaded. + +Engines which provide entirely new encryption algorithms (such as ccgost +engine which provides gost89 algorithm) should be configured in the +configuration file. Engines, specified in the command line using -engine +options can only be used for hadrware-assisted implementations of +ciphers, which are supported by OpenSSL core or other engine, specified +in the configuration file. + +When enc command lists supported ciphers, ciphers provided by engines, +specified in the configuration files are listed too. A password will be prompted for to derive the key and IV if necessary. @@ -169,6 +208,14 @@ Blowfish and RC5 algorithms use a 128 bit key. =head1 SUPPORTED CIPHERS +Note that some of these ciphers can be disabled at compile time +and some are available only if an appropriate engine is configured +in the configuration file. The output of the B command run with +unsupported options (for example B) includes a +list of ciphers, supported by your versesion of OpenSSL, including +ones provided by configured engines. + + base64 Base 64 bf-cbc Blowfish in CBC mode @@ -203,6 +250,9 @@ Blowfish and RC5 algorithms use a 128 bit key. desx DESX algorithm. + gost89 GOST 28147-89 in CFB mode (provided by ccgost engine) + gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine) + idea-cbc IDEA algorithm in CBC mode idea same as idea-cbc idea-cfb IDEA in CFB mode diff --git a/openssl/doc/apps/gendsa.pod b/openssl/doc/apps/gendsa.pod index 2c56cc788..8c7f114ca 100644 --- a/openssl/doc/apps/gendsa.pod +++ b/openssl/doc/apps/gendsa.pod @@ -40,7 +40,7 @@ all others. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/genpkey.pod b/openssl/doc/apps/genpkey.pod new file mode 100644 index 000000000..1611b5ca7 --- /dev/null +++ b/openssl/doc/apps/genpkey.pod @@ -0,0 +1,213 @@ +=pod + +=head1 NAME + +genpkey - generate a private key + +=head1 SYNOPSIS + +B B +[B<-out filename>] +[B<-outform PEM|DER>] +[B<-pass arg>] +[B<-cipher>] +[B<-engine id>] +[B<-paramfile file>] +[B<-algorithm alg>] +[B<-pkeyopt opt:value>] +[B<-genparam>] +[B<-text>] + +=head1 DESCRIPTION + +The B command generates a private key. + +=head1 OPTIONS + +=over 4 + +=item B<-out filename> + +the output filename. If this argument is not specified then standard output is +used. + +=item B<-outform DER|PEM> + +This specifies the output format DER or PEM. + +=item B<-pass arg> + +the output file password source. For more information about the format of B +see the B section in L. + +=item B<-cipher> + +This option encrypts the private key with the supplied cipher. Any algorithm +name accepted by EVP_get_cipherbyname() is acceptable such as B. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. If used this option should precede all other +options. + +=item B<-algorithm alg> + +public key algorithm to use such as RSA, DSA or DH. If used this option must +precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> +are mutually exclusive. + +=item B<-pkeyopt opt:value> + +set the public key algorithm option B to B. The precise set of +options supported depends on the public key algorithm used and its +implementation. See B below for more details. + +=item B<-genparam> + +generate a set of parameters instead of a private key. If used this option must +precede and B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. + +=item B<-paramfile filename> + +Some public key algorithms generate a private key based on a set of parameters. +They can be supplied using this option. If this option is used the public key +algorithm used is determined by the parameters. If used this option must +precede and B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> +are mutually exclusive. + +=item B<-text> + +Print an (unencrypted) text representation of private and public keys and +parameters along with the PEM or DER structure. + +=back + +=head1 KEY GENERATION OPTIONS + +The options supported by each algorith and indeed each implementation of an +algorithm can vary. The options for the OpenSSL implementations are detailed +below. + +=head1 RSA KEY GENERATION OPTIONS + +=over 4 + +=item B + +The number of bits in the generated key. If not specified 1024 is used. + +=item B + +The RSA public exponent value. This can be a large decimal or +hexadecimal value if preceded by B<0x>. Default value is 65537. + +=back + +=head1 DSA PARAMETER GENERATION OPTIONS + +=over 4 + +=item B + +The number of bits in the generated parameters. If not specified 1024 is used. + +=head1 DH PARAMETER GENERATION OPTIONS + +=over 4 + +=item B + +The number of bits in the prime parameter B

. + +=item B + +The value to use for the generator B. + +=back + +=head1 EC PARAMETER GENERATION OPTIONS + +=over 4 + +=item B + +the EC curve to use. + +=back + +=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS + +Gost 2001 support is not enabled by default. To enable this algorithm, +one should load the ccgost engine in the OpenSSL configuration file. +See README.gost file in the engines/ccgost directiry of the source +distribution for more details. + +Use of a parameter file for the GOST R 34.10 algorithm is optional. +Parameters can be specified during key generation directly as well as +during generation of parameter file. + +=over 4 + +=item B + +Specifies GOST R 34.10-2001 parameter set according to RFC 4357. +Parameter set can be specified using abbreviated name, object short name or +numeric OID. Following parameter sets are supported: + + paramset OID Usage + A 1.2.643.2.2.35.1 Signature + B 1.2.643.2.2.35.2 Signature + C 1.2.643.2.2.35.3 Signature + XA 1.2.643.2.2.36.0 Key exchange + XB 1.2.643.2.2.36.1 Key exchange + test 1.2.643.2.2.35.0 Test purposes + +=back + + + +=head1 NOTES + +The use of the genpkey program is encouraged over the algorithm specific +utilities because additional algorithm options and ENGINE provided algorithms +can be used. + +=head1 EXAMPLES + +Generate an RSA private key using default parameters: + + openssl genpkey -algorithm RSA -out key.pem + +Encrypt output private key using 128 bit AES and the passphrase "hello": + + openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello + +Generate a 2048 bit RSA key using 3 as the public exponent: + + openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \ + -pkeyopt rsa_keygen_pubexp:3 + +Generate 1024 bit DSA parameters: + + openssl genpkey -genparam -algorithm DSA -out dsap.pem \ + -pkeyopt dsa_paramgen_bits:1024 + +Generate DSA key from parameters: + + openssl genpkey -paramfile dsap.pem -out dsakey.pem + +Generate 1024 bit DH parameters: + + openssl genpkey -genparam -algorithm DH -out dhp.pem \ + -pkeyopt dh_paramgen_prime_len:1024 + +Generate DH key from parameters: + + openssl genpkey -paramfile dhp.pem -out dhkey.pem + + +=cut + diff --git a/openssl/doc/apps/genrsa.pod b/openssl/doc/apps/genrsa.pod index 25af4d147..7dcac2a77 100644 --- a/openssl/doc/apps/genrsa.pod +++ b/openssl/doc/apps/genrsa.pod @@ -57,7 +57,7 @@ all others. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/ocsp.pod b/openssl/doc/apps/ocsp.pod index b58ddc178..af2e12e41 100644 --- a/openssl/doc/apps/ocsp.pod +++ b/openssl/doc/apps/ocsp.pod @@ -51,6 +51,7 @@ B B [B<-ndays n>] [B<-resp_key_id>] [B<-nrequest n>] +[B<-md5|-sha1|...>] =head1 DESCRIPTION @@ -206,6 +207,11 @@ information is immediately available. In this case the age of the B f is checked to see it is not older than B seconds old. By default this additional check is not performed. +=item B<-md5|-sha1|-sha256|-ripemod160|...> + +this option sets digest algorithm to use for certificate identification +in the OCSP request. By default SHA-1 is used. + =back =head1 OCSP SERVER OPTIONS diff --git a/openssl/doc/apps/openssl.pod b/openssl/doc/apps/openssl.pod index 964cdf0f0..738142e9f 100644 --- a/openssl/doc/apps/openssl.pod +++ b/openssl/doc/apps/openssl.pod @@ -12,7 +12,7 @@ I [ I ] [ I ] -B [ B | B | B ] +B [ B | B | B | B | B | B] B BI [ I ] @@ -26,12 +26,14 @@ The B program is a command line tool for using the various cryptography functions of OpenSSL's B library from the shell. It can be used for - o Creation of RSA, DH and DSA key parameters + o Creation and management of private keys, public keys and parameters + o Public key cryptographic operations o Creation of X.509 certificates, CSRs and CRLs o Calculation of Message Digests o Encryption and Decryption with Ciphers o SSL/TLS Client and Server Tests o Handling of S/MIME signed or encrypted mail + o Time Stamp requests, generation and verification =head1 COMMAND SUMMARY @@ -44,6 +46,14 @@ and B output a list (one entry per line) of the names of all standard commands, message digest commands, or cipher commands, respectively, that are available in the present B utility. +The pseudo-commands B and +B list all cipher and message digest names, one entry per line. Aliases are listed as: + + from => to + +The pseudo-command B lists all supported public +key algorithms. + The pseudo-command BI tests whether a command of the specified name is available. If no command named I exists, it returns 0 (success) and prints BI; otherwise it returns 1 @@ -71,6 +81,10 @@ Certificate Authority (CA) Management. Cipher Suite Description Determination. +=item L|cms(1)> + +CMS (Cryptographic Message Syntax) utility + =item L|crl(1)> Certificate Revocation List (CRL) Management. @@ -88,25 +102,40 @@ Message Digest Calculation. Diffie-Hellman Parameter Management. Obsoleted by L|dhparam(1)>. +=item L|dhparam(1)> + +Generation and Management of Diffie-Hellman Parameters. Superseded by +L|genpkey(1)> and L|pkeyparam(1)> + + =item L|dsa(1)> DSA Data Management. =item L|dsaparam(1)> -DSA Parameter Generation. +DSA Parameter Generation and Management. Superseded by +L|genpkey(1)> and L|pkeyparam(1)> + +=item L|ec(1)> + +EC (Elliptic curve) key processing + +=item L|ecparam(1)> + +EC parameter manipulation and generation =item L|enc(1)> Encoding with Ciphers. -=item L|errstr(1)> +=item L|engine(1)> -Error Number to Error String Conversion. +Engine (loadble module) information and manipulation. -=item L|dhparam(1)> +=item L|errstr(1)> -Generation and Management of Diffie-Hellman Parameters. +Error Number to Error String Conversion. =item B @@ -115,11 +144,20 @@ Obsoleted by L|dhparam(1)>. =item L|gendsa(1)> -Generation of DSA Parameters. +Generation of DSA Private Key from Parameters. Superseded by +L|genpkey(1)> and L|pkey(1)> + +=item L|genpkey(1)> + +Generation of Private Key or Parameters. =item L|genrsa(1)> -Generation of RSA Parameters. +Generation of RSA Private Key. Superceded by L|genpkey(1)>. + +=item L|nseq(1)> + +Create or examine a netscape certificate sequence =item L|ocsp(1)> @@ -137,21 +175,35 @@ PKCS#12 Data Management. PKCS#7 Data Management. +=item L|pkey(1)> + +Public and private key management. + +=item L|pkeyparam(1)> + +Public key algorithm parameter management. + +=item L|pkeyutl(1)> + +Public key algorithm cryptographic operation utility. + =item L|rand(1)> Generate pseudo-random bytes. =item L|req(1)> -X.509 Certificate Signing Request (CSR) Management. +PKCS#10 X.509 Certificate Signing Request (CSR) Management. =item L|rsa(1)> -RSA Data Management. +RSA key management. + =item L|rsautl(1)> -RSA utility for signing, verification, encryption, and decryption. +RSA utility for signing, verification, encryption, and decryption. Superseded +by L|pkeyutl(1)> =item L|s_client(1)> @@ -185,6 +237,14 @@ S/MIME mail processing. Algorithm Speed Measurement. +=item L|spkac(1)> + +SPKAC printing and generating utility + +=item L|ts(1)> + +Time Stamping Authority tool (client/server) + =item L|verify(1)> X.509 Certificate Verification. @@ -227,6 +287,8 @@ SHA Digest SHA-1 Digest +=back + =item B SHA-224 Digest @@ -243,8 +305,6 @@ SHA-384 Digest SHA-512 Digest -=back - =head2 ENCODING AND CIPHER COMMANDS =over 10 @@ -339,7 +399,7 @@ read the password from standard input. L, L, L, L, L, L, L, L, L, -L, L, +L, L, L, L, L, L, L, L, L, L, @@ -348,12 +408,13 @@ L, L, L, L, L, L, L, L, L, -L, L +L, L, L =head1 HISTORY The openssl(1) document appeared in OpenSSL 0.9.2. The BIB<-commands> pseudo-commands were added in OpenSSL 0.9.3; +The BIB<-algorithms> pseudo-commands were added in OpenSSL 1.0.0; the BI pseudo-commands were added in OpenSSL 0.9.5a. For notes on the availability of other commands, see their individual manual pages. diff --git a/openssl/doc/apps/pkcs12.pod b/openssl/doc/apps/pkcs12.pod index 7d8414629..f69a5c5a4 100644 --- a/openssl/doc/apps/pkcs12.pod +++ b/openssl/doc/apps/pkcs12.pod @@ -23,22 +23,23 @@ B B [B<-cacerts>] [B<-nokeys>] [B<-info>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-nodes>] +[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>] [B<-noiter>] -[B<-maciter>] +[B<-maciter | -nomaciter | -nomac>] [B<-twopass>] [B<-descert>] -[B<-certpbe>] -[B<-keypbe>] +[B<-certpbe cipher>] +[B<-keypbe cipher>] +[B<-macalg digest>] [B<-keyex>] [B<-keysig>] [B<-password arg>] [B<-passin arg>] [B<-passout arg>] [B<-rand file(s)>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-CSP name>] =head1 DESCRIPTION @@ -49,7 +50,7 @@ programs including Netscape, MSIE and MS Outlook. =head1 COMMAND OPTIONS There are a lot of options the meaning of some depends of whether a PKCS#12 file -is being created or parsed. By default a PKCS#12 file is parsed a PKCS#12 +is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 file can be created by using the B<-export> option (see below). =head1 PARSING OPTIONS @@ -63,25 +64,25 @@ by default. =item B<-out filename> -The filename to write certificates and private keys to, standard output by default. -They are all written in PEM format. +The filename to write certificates and private keys to, standard output by +default. They are all written in PEM format. =item B<-pass arg>, B<-passin arg> -the PKCS#12 file (i.e. input file) password source. For more information about the -format of B see the B section in +the PKCS#12 file (i.e. input file) password source. For more information about +the format of B see the B section in L. =item B<-passout arg> -pass phrase source to encrypt any outputed private keys with. For more information -about the format of B see the B section in -L. +pass phrase source to encrypt any outputed private keys with. For more +information about the format of B see the B section +in L. =item B<-noout> -this option inhibits output of the keys and certificates to the output file version -of the PKCS#12 file. +this option inhibits output of the keys and certificates to the output file +version of the PKCS#12 file. =item B<-clcerts> @@ -116,6 +117,14 @@ use triple DES to encrypt private keys before outputting, this is the default. use IDEA to encrypt private keys before outputting. +=item B<-aes128>, B<-aes192>, B<-aes256> + +use AES to encrypt private keys before outputting. + +=item B<-camellia128>, B<-camellia192>, B<-camellia256> + +use Camellia to encrypt private keys before outputting. + =item B<-nodes> don't encrypt the private keys at all. @@ -148,10 +157,10 @@ by default. =item B<-in filename> -The filename to read certificates and private keys from, standard input by default. -They must all be in PEM format. The order doesn't matter but one private key and -its corresponding certificate should be present. If additional certificates are -present they will also be included in the PKCS#12 file. +The filename to read certificates and private keys from, standard input by +default. They must all be in PEM format. The order doesn't matter but one +private key and its corresponding certificate should be present. If additional +certificates are present they will also be included in the PKCS#12 file. =item B<-inkey filename> @@ -160,8 +169,8 @@ in the input file. =item B<-name friendlyname> -This specifies the "friendly name" for the certificate and private key. This name -is typically displayed in list boxes by software importing the file. +This specifies the "friendly name" for the certificate and private key. This +name is typically displayed in list boxes by software importing the file. =item B<-certfile filename> @@ -201,9 +210,11 @@ key is encrypted using triple DES and the certificate using 40 bit RC2. =item B<-keypbe alg>, B<-certpbe alg> these options allow the algorithm used to encrypt the private key and -certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms -can be selected it is advisable only to use PKCS#12 algorithms. See the list -in the B section for more information. +certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name +can be used (see B section for more information). If a a cipher name +(as output by the B command is specified then it +is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only +use PKCS#12 algorithms. =item B<-keyex|-keysig> @@ -216,6 +227,10 @@ S/MIME signing, authenticode (ActiveX control signing) and SSL client authentication, however due to a bug only MSIE 5.0 and later support the use of signing only keys for SSL client authentication. +=item B<-macalg digest> + +specify the MAC digest algorithm. If not included them SHA1 will be used. + =item B<-nomaciter>, B<-noiter> these options affect the iteration counts on the MAC and key algorithms. @@ -239,6 +254,10 @@ option. This option is included for compatibility with previous versions, it used to be needed to use MAC iterations counts but they are now used by default. +=item B<-nomac> + +don't attempt to provide the MAC integrity. + =item B<-rand file(s)> a file or files containing random data used to seed the random number @@ -247,6 +266,20 @@ Multiple files can be specified separated by a OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. +=item B<-CAfile file> + +CA storage as a file. + +=item B<-CApath dir> + +CA storage as a directory. This directory must be a standard certificate +directory: that is a hash of each subject name (using B) should be +linked to each certificate. + +=item B<-CSP name> + +write B as a Microsoft CSP name. + =back =head1 NOTES diff --git a/openssl/doc/apps/pkcs7.pod b/openssl/doc/apps/pkcs7.pod index a0a636328..acfb8100f 100644 --- a/openssl/doc/apps/pkcs7.pod +++ b/openssl/doc/apps/pkcs7.pod @@ -62,7 +62,7 @@ is B<-print_certs> is set). =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/pkcs8.pod b/openssl/doc/apps/pkcs8.pod index 68ecd65b1..84abee78f 100644 --- a/openssl/doc/apps/pkcs8.pod +++ b/openssl/doc/apps/pkcs8.pod @@ -125,7 +125,7 @@ list of possible algorithms is included below. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/pkey.pod b/openssl/doc/apps/pkey.pod new file mode 100644 index 000000000..4851223f3 --- /dev/null +++ b/openssl/doc/apps/pkey.pod @@ -0,0 +1,135 @@ + +=pod + +=head1 NAME + +pkey - public or private key processing tool + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-cipher>] +[B<-text>] +[B<-text_pub>] +[B<-noout>] +[B<-pubin>] +[B<-pubout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B command processes public or private keys. They can be converted +between various forms and their components printed out. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format DER or PEM. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a key from or standard input if this +option is not specified. If the key is encrypted a pass phrase will be +prompted for. + +=item B<-passin arg> + +the input file password source. For more information about the format of B +see the B section in L. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output if this +option is not specified. If any encryption options are set then a pass phrase +will be prompted for. The output filename should B be the same as the input +filename. + +=item B<-passout password> + +the output file password source. For more information about the format of B +see the B section in L. + +=item B<-cipher> + +These options encrypt the private key with the supplied cipher. Any algorithm +name accepted by EVP_get_cipherbyname() is acceptable such as B. + +=item B<-text> + +prints out the various public or private key components in +plain text in addition to the encoded version. + +=item B<-text_pub> + +print out only public key components even if a private key is being processed. + +=item B<-noout> + +do not output the encoded version of the key. + +=item B<-pubin> + +by default a private key is read from the input file: with this +option a public key is read instead. + +=item B<-pubout> + +by default a private key is output: with this option a public +key will be output instead. This option is automatically set if +the input is a public key. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLES + +To remove the pass phrase on an RSA private key: + + openssl pkey -in key.pem -out keyout.pem + +To encrypt a private key using triple DES: + + openssl pkey -in key.pem -des3 -out keyout.pem + +To convert a private key from PEM to DER format: + + openssl pkey -in key.pem -outform DER -out keyout.der + +To print out the components of a private key to standard output: + + openssl pkey -in key.pem -text -noout + +To print out the public components of a private key to standard output: + + openssl pkey -in key.pem -text_pub -noout + +To just output the public part of a private key: + + openssl pkey -in key.pem -pubout -out pubkey.pem + +=head1 SEE ALSO + +L, L, L, +L, L, L + +=cut diff --git a/openssl/doc/apps/pkeyparam.pod b/openssl/doc/apps/pkeyparam.pod new file mode 100644 index 000000000..154f6721a --- /dev/null +++ b/openssl/doc/apps/pkeyparam.pod @@ -0,0 +1,69 @@ + +=pod + +=head1 NAME + +pkeyparam - public key algorithm parameter processing tool + +=head1 SYNOPSIS + +B B +[B<-in filename>] +[B<-out filename>] +[B<-text>] +[B<-noout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B command processes public or private keys. They can be converted +between various forms and their components printed out. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. + +=item B<-out filename> + +This specifies the output filename to write parameters to or standard output if +this option is not specified. + +=item B<-text> + +prints out the parameters in plain text in addition to the encoded version. + +=item B<-noout> + +do not output the encoded version of the parameters. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLE + +Print out text version of parameters: + + openssl pkeyparam -in param.pem -text + +=head1 NOTES + +There are no B<-inform> or B<-outform> options for this command because only +PEM format is supported because the key type is determined by the PEM headers. + +=head1 SEE ALSO + +L, L, L, +L, L, L + +=cut diff --git a/openssl/doc/apps/pkeyutl.pod b/openssl/doc/apps/pkeyutl.pod new file mode 100644 index 000000000..27be9a900 --- /dev/null +++ b/openssl/doc/apps/pkeyutl.pod @@ -0,0 +1,222 @@ +=pod + +=head1 NAME + +pkeyutl - public key algorithm utility + +=head1 SYNOPSIS + +B B +[B<-in file>] +[B<-out file>] +[B<-sigfile file>] +[B<-inkey file>] +[B<-keyform PEM|DER>] +[B<-passin arg>] +[B<-peerkey file>] +[B<-peerform PEM|DER>] +[B<-pubin>] +[B<-certin>] +[B<-rev>] +[B<-sign>] +[B<-verify>] +[B<-verifyrecover>] +[B<-encrypt>] +[B<-decrypt>] +[B<-derive>] +[B<-pkeyopt opt:value>] +[B<-hexdump>] +[B<-asn1parse>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B command can be used to perform public key operations using +any supported algorithm. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies the input filename to read data from or standard input +if this option is not specified. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-inkey file> + +the input key file, by default it should be a private key. + +=item B<-keyform PEM|DER> + +the key format PEM, DER or ENGINE. + +=item B<-passin arg> + +the input key password source. For more information about the format of B +see the B section in L. + + +=item B<-peerkey file> + +the peer key file, used by key derivation (agreement) operations. + +=item B<-peerform PEM|DER> + +the peer key format PEM, DER or ENGINE. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + + +=item B<-pubin> + +the input file is a public key. + +=item B<-certin> + +the input is a certificate containing a public key. + +=item B<-rev> + +reverse the order of the input buffer. This is useful for some libraries +(such as CryptoAPI) which represent the buffer in little endian format. + +=item B<-sign> + +sign the input data and output the signed result. This requires +a private key. + +=item B<-verify> + +verify the input data against the signature file and indicate if the +verification succeeded or failed. + +=item B<-verifyrecover> + +verify the input data and output the recovered data. + +=item B<-encrypt> + +encrypt the input data using a public key. + +=item B<-decrypt> + +decrypt the input data using a private key. + +=item B<-derive> + +derive a shared secret using the peer key. + +=item B<-hexdump> + +hex dump the output data. + +=item B<-asn1parse> + +asn1parse the output data, this is useful when combined with the +B<-verifyrecover> option when an ASN1 structure is signed. + +=back + +=head1 NOTES + +The operations and options supported vary according to the key algorithm +and its implementation. The OpenSSL operations and options are indicated below. + +Unless otherwise mentioned all algorithms support the B option +which specifies the digest in use for sign, verify and verifyrecover operations. +The value B should represent a digest name as used in the +EVP_get_digestbyname() function for example B. + +=head1 RSA ALGORITHM + +The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover +operations in general. Some padding modes only support some of these +operations however. + +=over 4 + +=item -B + +This sets the RSA padding mode. Acceptable values for B are B for +PKCS#1 padding, B for SSLv23 padding, B for no padding, B +for B mode, B for X9.31 mode and B for PSS. + +In PKCS#1 padding if the message digest is not set then the supplied data is +signed or verified directly instead of using a B structure. If a +digest is set then the a B structure is used and its the length +must correspond to the digest type. + +For B mode only encryption and decryption is supported. + +For B if the digest type is set it is used to format the block data +otherwise the first byte is used to specify the X9.31 digest ID. Sign, +verify and verifyrecover are can be performed in this mode. + +For B mode only sign and verify are supported and the digest type must be +specified. + +=item B + +For B mode only this option specifies the salt length. 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. + +=back + +=head1 DSA ALGORITHM + +The DSA algorithm supports signing and verification operations only. Currently +there are no additional options other than B. Only the SHA1 +digest can be used and this digest is assumed by default. + +=head1 DH ALGORITHM + +The DH algorithm only supports the derivation operation and no additional +options. + +=head1 EC ALGORITHM + +The EC algorithm supports sign, verify and derive operations. The sign and +verify operations use ECDSA and derive uses ECDH. Currently there are no +additional options other than B. Only the SHA1 digest can be used and +this digest is assumed by default. + +=head1 EXAMPLES + +Sign some data using a private key: + + openssl pkeyutl -sign -in file -inkey key.pem -out sig + +Recover the signed data (e.g. if an RSA key is used): + + openssl pkeyutl -verifyrecover -in sig -inkey key.pem + +Verify the signature (e.g. a DSA key): + + openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem + +Sign data using a message digest value (this is currently only valid for RSA): + + openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 + +Derive a shared secret value: + + openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret + +=head1 SEE ALSO + +L, L, L +L, L, L diff --git a/openssl/doc/apps/req.pod b/openssl/doc/apps/req.pod index 82b565c9d..ff48bbdf2 100644 --- a/openssl/doc/apps/req.pod +++ b/openssl/doc/apps/req.pod @@ -22,12 +22,13 @@ B B [B<-new>] [B<-rand file(s)>] [B<-newkey rsa:bits>] -[B<-newkey dsa:file>] +[B<-newkey alg:file>] [B<-nodes>] [B<-key filename>] [B<-keyform PEM|DER>] [B<-keyout filename>] -[B<-[md5|sha1|md2|mdc2]>] +[B<-keygen_engine id>] +[B<-[digest]>] [B<-config filename>] [B<-subj arg>] [B<-multivalue-rdn>] @@ -35,11 +36,15 @@ B B [B<-days n>] [B<-set_serial n>] [B<-asn1-kludge>] +[B<-no-asn1-kludge>] [B<-newhdr>] [B<-extensions section>] [B<-reqexts section>] [B<-utf8>] [B<-nameopt>] +[B<-reqopt>] +[B<-subject>] +[B<-subj arg>] [B<-batch>] [B<-verbose>] [B<-engine id>] @@ -91,6 +96,11 @@ see the B section in L. prints out the certificate request in text form. +=item B<-subject> + +prints out the request subject (or certificate subject if B<-x509> is +specified) + =item B<-pubkey> outputs the public key. @@ -118,6 +128,13 @@ in the configuration file and any requested extensions. If the B<-key> option is not used it will generate a new RSA private key using information specified in the configuration file. +=item B<-subj arg> + +Replaces subject field of input request with specified data and outputs +modified request. The arg must be formatted as +I, +characters may be escaped by \ (backslash), no spaces are skipped. + =item B<-rand file(s)> a file or files containing random data used to seed the random number @@ -129,10 +146,35 @@ all others. =item B<-newkey arg> this option creates a new certificate request and a new private -key. The argument takes one of two forms. B, where +key. The argument takes one of several forms. B, where B is the number of bits, generates an RSA key B -in size. B generates a DSA key using the parameters -in the file B. +in size. If B is omitted, i.e. B<-newkey rsa> specified, +the default key size, specified in the configuration file is used. + +All other algorithms support the B<-newkey alg:file> form, where file may be +an algorithm parameter file, created by the B command +or and X.509 certificate for a key with approriate algorithm. + +B generates a key using the parameter file or certificate B, +the algorithm is determined by the parameters. B use algorithm +B and parameter file B: the two algorithms must match or an +error occurs. B just uses algorithm B, and parameters, +if neccessary should be specified via B<-pkeyopt> parameter. + +B generates a DSA key using the parameters +in the file B. B generates EC key (usable both with +ECDSA or ECDH algorithms), B generates GOST R +34.10-2001 key (requires B engine configured in the configuration +file). If just B is specified a parameter set should be +specified by B<-pkeyopt paramset:X> + + +=item B<-pkeyopt opt:value> + +set the public key algorithm option B to B. The precise set of +options supported depends on the public key algorithm used and its +implementation. See B in the B manual page +for more details. =item B<-key filename> @@ -155,11 +197,15 @@ configuration file is used. if this option is specified then if a private key is created it will not be encrypted. -=item B<-[md5|sha1|md2|mdc2]> +=item B<-[digest]> + +this specifies the message digest to sign the request with (such as +B<-md5>, B<-sha1>). This overrides the digest algorithm specified in +the configuration file. -this specifies the message digest to sign the request with. This -overrides the digest algorithm specified in the configuration file. -This option is ignored for DSA requests: they always use SHA1. +Some public key algorithms may override this choice. For instance, DSA +signatures always use SHA1, GOST R 34.10 signatures always use +GOST R 34.11-94 (B<-md_gost94>). =item B<-config filename> @@ -227,6 +273,15 @@ 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); diff --git a/openssl/doc/ssl/SSL_CIPHER_get_name.pod b/openssl/doc/ssl/SSL_CIPHER_get_name.pod index f62a869a9..eb772b55d 100644 --- a/openssl/doc/ssl/SSL_CIPHER_get_name.pod +++ b/openssl/doc/ssl/SSL_CIPHER_get_name.pod @@ -11,7 +11,7 @@ SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_des const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); - char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size); + char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size); =head1 DESCRIPTION diff --git a/openssl/doc/ssl/SSL_CTX_new.pod b/openssl/doc/ssl/SSL_CTX_new.pod index 465220a75..73e8c47f9 100644 --- a/openssl/doc/ssl/SSL_CTX_new.pod +++ b/openssl/doc/ssl/SSL_CTX_new.pod @@ -8,7 +8,7 @@ SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled funct #include - SSL_CTX *SSL_CTX_new(SSL_METHOD *method); + SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); =head1 DESCRIPTION diff --git a/openssl/doc/ssl/SSL_CTX_set_mode.pod b/openssl/doc/ssl/SSL_CTX_set_mode.pod index 9822544e5..8cb669dae 100644 --- a/openssl/doc/ssl/SSL_CTX_set_mode.pod +++ b/openssl/doc/ssl/SSL_CTX_set_mode.pod @@ -61,6 +61,16 @@ deal with read/write operations returning without success report. The flag SSL_MODE_AUTO_RETRY will cause read/write operations to only return after the handshake and successful completion. +=item SSL_MODE_RELEASE_BUFFERS + +When we no longer need a read buffer or a write buffer for a given SSL, +then release the memory we were using to hold it. Released memory is +either appended to a list of unused RAM chunks on the SSL_CTX, or simply +freed if the list of unused chunks would become longer than +SSL_CTX->freelist_max_len, which defaults to 32. Using this flag can +save around 34k per idle SSL connection. +This flag has no effect on SSL v2 connections, or on DTLS connections. + =back =head1 RETURN VALUES diff --git a/openssl/doc/ssl/SSL_CTX_set_options.pod b/openssl/doc/ssl/SSL_CTX_set_options.pod index eaed19080..310db84b3 100644 --- a/openssl/doc/ssl/SSL_CTX_set_options.pod +++ b/openssl/doc/ssl/SSL_CTX_set_options.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options +SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support - manipulate SSL options =head1 SYNOPSIS @@ -11,26 +11,41 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - man long SSL_CTX_set_options(SSL_CTX *ctx, long options); long SSL_set_options(SSL *ssl, long options); + long SSL_CTX_clear_options(SSL_CTX *ctx, long options); + long SSL_clear_options(SSL *ssl, long options); + long SSL_CTX_get_options(SSL_CTX *ctx); long SSL_get_options(SSL *ssl); + long SSL_get_secure_renegotiation_support(SSL *ssl); + =head1 DESCRIPTION +Note: all these functions are implemented using macros. + SSL_CTX_set_options() adds the options set via bitmask in B to B. Options already set before are not cleared! SSL_set_options() adds the options set via bitmask in B to B. Options already set before are not cleared! +SSL_CTX_clear_options() clears the options set via bitmask in B +to B. + +SSL_clear_options() clears the options set via bitmask in B to B. + SSL_CTX_get_options() returns the options set for B. SSL_get_options() returns the options set for B. +SSL_get_secure_renegotiation_support() indicates whether the peer supports +secure renegotiation. + =head1 NOTES The behaviour of the SSL library can be changed by setting several options. The options are coded as bitmasks and can be combined by a logical B -operation (|). Options can only be added but can never be reset. +operation (|). SSL_CTX_set_options() and SSL_set_options() affect the (external) protocol behaviour of the SSL library. The (internal) behaviour of @@ -199,26 +214,117 @@ Do not use the TLSv1 protocol. When performing renegotiation as a server, always start a new session (i.e., session resumption requests are only accepted in the initial -handshake). This option is not needed for clients. +handshake). This option is not needed for clients. =item SSL_OP_NO_TICKET Normally clients and servers will, where possible, transparently make use -of RFC4507bis tickets for stateless session resumption if extension support -is explicitly set when OpenSSL is compiled. +of RFC4507bis tickets for stateless session resumption. If this option is set this functionality is disabled and tickets will not be used by clients or servers. +=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION + +Allow legacy insecure renegotiation between OpenSSL and unpatched clients or +servers. See the B section for more details. + +=item SSL_OP_LEGACY_SERVER_CONNECT + +Allow legacy insecure renegotiation between OpenSSL and unpatched servers +B: this option is currently set by default. See the +B section for more details. + =back +=head1 SECURE RENEGOTIATION + +OpenSSL 0.9.8m and later always attempts to use secure renegotiation as +described in RFC5746. This counters the prefix attack described in +CVE-2009-3555 and elsewhere. + +The deprecated and highly broken SSLv2 protocol does not support +renegotiation at all: its use is B discouraged. + +This attack has far reaching consequences which application writers should be +aware of. In the description below an implementation supporting secure +renegotiation is referred to as I. A server not supporting secure +renegotiation is referred to as I. + +The following sections describe the operations permitted by OpenSSL's secure +renegotiation implementation. + +=head2 Patched client and server + +Connections and renegotiation are always permitted by OpenSSL implementations. + +=head2 Unpatched client and patched OpenSSL server + +The initial connection suceeds but client renegotiation is denied by the +server with a B warning alert if TLS v1.0 is used or a fatal +B alert in SSL v3.0. + +If the patched OpenSSL server attempts to renegotiate a fatal +B alert is sent. This is because the server code may be +unaware of the unpatched nature of the client. + +If the option B is set then +renegotiation B succeeds. + +B a bug in OpenSSL clients earlier than 0.9.8m (all of which are +unpatched) will result in the connection hanging if it receives a +B alert. OpenSSL versions 0.9.8m and later will regard +a B alert as fatal and respond with a fatal +B alert. This is because the OpenSSL API currently has +no provision to indicate to an application that a renegotiation attempt +was refused. + +=head2 Patched OpenSSL client and unpatched server. + +If the option B or +B is set then initial connections +and renegotiation between patched OpenSSL clients and unpatched servers +succeeds. If neither option is set then initial connections to unpatched +servers will fail. + +The option B is currently set by default even +though it has security implications: otherwise it would be impossible to +connect to unpatched servers (i.e. all of them initially) and this is clearly +not acceptable. Renegotiation is permitted because this does not add any +additional security issues: during an attack clients do not see any +renegotiations anyway. + +As more servers become patched the option B will +B be set by default in a future version of OpenSSL. + +OpenSSL client applications wishing to ensure they can connect to unpatched +servers should always B B + +OpenSSL client applications that want to ensure they can B connect to +unpatched servers (and thus avoid any security issues) should always B +B using SSL_CTX_clear_options() or +SSL_clear_options(). + +The difference between the B and +B options is that +B enables initial connections and secure +renegotiation between OpenSSL clients and unpatched servers B, while +B allows initial connections +and renegotiation between OpenSSL and unpatched clients or servers. + =head1 RETURN VALUES SSL_CTX_set_options() and SSL_set_options() return the new options bitmask after adding B. +SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask +after clearing B. + SSL_CTX_get_options() and SSL_get_options() return the current bitmask. +SSL_get_secure_renegotiation_support() returns 1 is the peer supports +secure renegotiation and 0 if it does not. + =head1 SEE ALSO L, L, L, @@ -241,4 +347,11 @@ Versions up to OpenSSL 0.9.6c do not include the countermeasure that can be disabled with this option (in OpenSSL 0.9.6d, it was always enabled). +SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL +0.9.8m. + +B, B +and the function SSL_get_secure_renegotiation_support() were first added in +OpenSSL 0.9.8m. + =cut diff --git a/openssl/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/openssl/doc/ssl/SSL_CTX_set_psk_client_callback.pod new file mode 100644 index 000000000..573f89a92 --- /dev/null +++ b/openssl/doc/ssl/SSL_CTX_set_psk_client_callback.pod @@ -0,0 +1,81 @@ +=pod + +=begin comment + +Copyright 2005 Nokia. All rights reserved. + +The portions of the attached software ("Contribution") is developed by +Nokia Corporation and is licensed pursuant to the OpenSSL open source +license. + +The Contribution, originally written by Mika Kousa and Pasi Eronen of +Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites +support (see RFC 4279) to OpenSSL. + +No patent licenses or other rights except those expressly stated in +the OpenSSL open source license shall be deemed granted or received +expressly, by implication, estoppel, or otherwise. + +No assurances are provided by Nokia that the Contribution does not +infringe the patent or other intellectual property rights of any third +party or that the license provides you with all the necessary rights +to make use of the Contribution. + +THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN +ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA +SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY +OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR +OTHERWISE. + +=end comment + +=head1 NAME + +SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback + +=head1 SYNOPSIS + + #include + + void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, + unsigned int (*callback)(SSL *ssl, const char *hint, + char *identity, unsigned int max_identity_len, + unsigned char *psk, unsigned int max_psk_len)); + void SSL_set_psk_client_callback(SSL *ssl, + unsigned int (*callback)(SSL *ssl, const char *hint, + char *identity, unsigned int max_identity_len, + unsigned char *psk, unsigned int max_psk_len)); + + +=head1 DESCRIPTION + +A client application must provide a callback function which is called +when the client is sending the ClientKeyExchange message to the server. + +The purpose of the callback function is to select the PSK identity and +the pre-shared key to use during the connection setup phase. + +The callback is set using functions SSL_CTX_set_psk_client_callback() +or SSL_set_psk_client_callback(). The callback function is given the +connection in parameter B, a B-terminated PSK identity hint +sent by the server in parameter B, a buffer B of +length B bytes where the the resulting +B-terminated identity is to be stored, and a buffer B of +length B bytes where the resulting pre-shared key is to +be stored. + +=head1 NOTES + +Note that parameter B given to the callback may be B. + +=head1 RETURN VALUES + +Return values from the client callback are interpreted as follows: + +On success (callback found a PSK identity and a pre-shared key to use) +the length (> 0) of B in bytes is returned. + +Otherwise or on errors callback should return 0. In this case +the connection setup fails. + +=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod b/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod index 002018096..254f2b439 100644 --- a/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod +++ b/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -9,9 +9,9 @@ SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method #include - int SSL_CTX_set_ssl_version(SSL_CTX *ctx, SSL_METHOD *method); - int SSL_set_ssl_method(SSL *s, SSL_METHOD *method); - SSL_METHOD *SSL_get_ssl_method(SSL *ssl); + int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *method); + int SSL_set_ssl_method(SSL *s, const SSL_METHOD *method); + const SSL_METHOD *SSL_get_ssl_method(SSL *ssl); =head1 DESCRIPTION diff --git a/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod new file mode 100644 index 000000000..b80e25be7 --- /dev/null +++ b/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod @@ -0,0 +1,102 @@ +=pod + +=begin comment + +Copyright 2005 Nokia. All rights reserved. + +The portions of the attached software ("Contribution") is developed by +Nokia Corporation and is licensed pursuant to the OpenSSL open source +license. + +The Contribution, originally written by Mika Kousa and Pasi Eronen of +Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites +support (see RFC 4279) to OpenSSL. + +No patent licenses or other rights except those expressly stated in +the OpenSSL open source license shall be deemed granted or received +expressly, by implication, estoppel, or otherwise. + +No assurances are provided by Nokia that the Contribution does not +infringe the patent or other intellectual property rights of any third +party or that the license provides you with all the necessary rights +to make use of the Contribution. + +THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN +ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA +SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY +OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR +OTHERWISE. + +=end comment + +=head1 NAME + +SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint, +SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK +identity hint to use + + +=head1 SYNOPSIS + + #include + + int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); + int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); + + void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, + unsigned int (*callback)(SSL *ssl, const char *identity, + unsigned char *psk, int max_psk_len)); + void SSL_set_psk_server_callback(SSL *ssl, + unsigned int (*callback)(SSL *ssl, const char *identity, + unsigned char *psk, int max_psk_len)); + + +=head1 DESCRIPTION + +SSL_CTX_use_psk_identity_hint() sets the given B-terminated PSK +identity hint B to SSL context object +B. SSL_use_psk_identity_hint() sets the given B-terminated +PSK identity hint B to SSL connection object B. If B +is B the current hint from B or B is deleted. + +In the case where PSK identity hint is B, the server +does not send the ServerKeyExchange message to the client. + +A server application must provide a callback function which is called +when the server receives the ClientKeyExchange message from the +client. The purpose of the callback function is to validate the +received PSK identity and to fetch the pre-shared key used during the +connection setup phase. The callback is set using functions +SSL_CTX_set_psk_server_callback() or +SSL_set_psk_server_callback(). The callback function is given the +connection in parameter B, B-terminated PSK identity sent +by the client in parameter B, and a buffer B of length +B bytes where the pre-shared key is to be stored. + + +=head1 RETURN VALUES + +SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return +1 on success, 0 otherwise. + +Return values from the server callback are interpreted as follows: + +=item > 0 + +PSK identity was found and the server callback has provided the PSK +successfully in parameter B. Return value is the length of +B in bytes. It is an error to return a value greater than +B. + +If the PSK identity was not found but the callback instructs the +protocol to continue anyway, the callback must provide some random +data to B and return the length of the random data, so the +connection will fail with decryption_error before it will be finished +completely. + +=item 0 + +PSK identity was not found. An "unknown_psk_identity" alert message +will be sent and the connection setup fails. + +=cut diff --git a/openssl/doc/ssl/SSL_get_psk_identity.pod b/openssl/doc/ssl/SSL_get_psk_identity.pod new file mode 100644 index 000000000..fe6291649 --- /dev/null +++ b/openssl/doc/ssl/SSL_get_psk_identity.pod @@ -0,0 +1,63 @@ +=pod + +=begin comment + +Copyright 2005 Nokia. All rights reserved. + +The portions of the attached software ("Contribution") is developed by +Nokia Corporation and is licensed pursuant to the OpenSSL open source +license. + +The Contribution, originally written by Mika Kousa and Pasi Eronen of +Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites +support (see RFC 4279) to OpenSSL. + +No patent licenses or other rights except those expressly stated in +the OpenSSL open source license shall be deemed granted or received +expressly, by implication, estoppel, or otherwise. + +No assurances are provided by Nokia that the Contribution does not +infringe the patent or other intellectual property rights of any third +party or that the license provides you with all the necessary rights +to make use of the Contribution. + +THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN +ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA +SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY +OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR +OTHERWISE. + +=end comment + +=head1 NAME + +SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and hint + + +=head1 SYNOPSIS + + #include + + const char *SSL_get_psk_identity_hint(const SSL *ssl); + const char *SSL_get_psk_identity(const SSL *ssl); + + +=head1 DESCRIPTION + +SSL_get_psk_identity_hint() is used to retrieve the PSK identity hint +used during the connection setup related to SSL object +B. Similarly, SSL_get_psk_identity() is used to retrieve the PSK +identity used during the connection setup. + + +=head1 RETURN VALUES + +If non-B, SSL_get_psk_identity_hint() returns the PSK identity +hint and SSL_get_psk_identity() returns the PSK identity. Both are +B-terminated. SSL_get_psk_identity_hint() may return B if +no PSK identity hint was used during the connection setup. + +Note that the return value is valid only during the lifetime of the +SSL object B. + +=cut diff --git a/openssl/doc/ssl/SSL_library_init.pod b/openssl/doc/ssl/SSL_library_init.pod index ecf3c4858..eed526e47 100644 --- a/openssl/doc/ssl/SSL_library_init.pod +++ b/openssl/doc/ssl/SSL_library_init.pod @@ -23,6 +23,7 @@ for SSL_library_init(). =head1 NOTES SSL_library_init() must be called before any other action takes place. +SSL_library_init() is not reentrant. =head1 WARNING diff --git a/openssl/doc/ssl/ssl.pod b/openssl/doc/ssl/ssl.pod index 266697d22..2b6004ee3 100644 --- a/openssl/doc/ssl/ssl.pod +++ b/openssl/doc/ssl/ssl.pod @@ -130,39 +130,39 @@ protocol methods defined in B structures. =over 4 -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the SSLv2 SSL_METHOD structure for a dedicated client. -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the SSLv2 SSL_METHOD structure for a dedicated server. -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the SSLv2 SSL_METHOD structure for combined client and server. -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the SSLv3 SSL_METHOD structure for combined client and server. -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. -=item SSL_METHOD *B(void); +=item cosnt SSL_METHOD *B(void); Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. -=item SSL_METHOD *B(void); +=item const SSL_METHOD *B(void); Constructor for the TLSv1 SSL_METHOD structure for combined client and server. @@ -249,7 +249,7 @@ protocol context defined in the B structure. =item long B(SSL_CTX *ctx); -=item SSL_CTX *B(SSL_METHOD *meth); +=item SSL_CTX *B(const SSL_METHOD *meth); =item int B(SSL_CTX *ctx, SSL_SESSION *c); @@ -327,7 +327,7 @@ protocol context defined in the B structure. =item void B(SSL_CTX *ctx, int mode); -=item int B(SSL_CTX *ctx, SSL_METHOD *meth); +=item int B(SSL_CTX *ctx, const SSL_METHOD *meth); =item void B(SSL_CTX *ctx, long t); @@ -374,6 +374,15 @@ session instead of a context. =item int B(SSL_CTX *ctx, char *file, int type); +=item void B(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); + +=item int B(SSL_CTX *ctx, const char *hint); + +=item void B(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); + + + + =back =head2 DEALING WITH SESSIONS @@ -512,7 +521,7 @@ connection defined in the B structure. =item int B(const SSL *ssl); -=item SSL_METHOD *B(SSL *ssl); +=item const SSL_METHOD *B(SSL *ssl); =item int B(const SSL *ssl); @@ -596,7 +605,7 @@ connection defined in the B structure. =item void B(SSL *ssl, int mode); -=item int B(SSL *ssl, SSL_METHOD *meth); +=item int B(SSL *ssl, const SSL_METHOD *meth); =item void B(SSL *ssl, long t); @@ -650,6 +659,16 @@ connection defined in the B structure. =item int B(SSL *ssl, const void *buf, int num); +=item void B(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); + +=item int B(SSL *ssl, const char *hint); + +=item void B(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); + +=item const char *B(SSL *ssl); + +=item const char *B(SSL *ssl); + =back =head1 SEE ALSO @@ -726,7 +745,10 @@ L, L, L, L, -L +L, +L, +L, +L =head1 HISTORY diff --git a/openssl/doc/ssleay.txt b/openssl/doc/ssleay.txt index a8b04d705..4d2e71486 100644 --- a/openssl/doc/ssleay.txt +++ b/openssl/doc/ssleay.txt @@ -20,7 +20,7 @@ don't do that. ==== readme ======================================================== This is the old 0.6.6 docuementation. Most of the cipher stuff is still -relevent but I'm working (very slowly) on new docuemtation. +relevent but I'm working (very slowly) on new documentation. The current version can be found online at http://www.cryptsoft.com/ssleay/doc @@ -548,8 +548,8 @@ application, ssleay. This one program is composed of many programs that can all be compiled independantly. ssleay has 3 modes of operation. -1) If the ssleay binaray has the name of one of its component programs, it -executes that program and then exits. This can be achieve by using hard or +1) If the ssleay binary has the name of one of its component programs, it +executes that program and then exits. This can be achieved by using hard or symbolic links, or failing that, just renaming the binary. 2) If the first argument to ssleay is the name of one of the component programs, that program runs that program and then exits. @@ -1185,7 +1185,7 @@ typedef struct bio_st example is for BIO_s_sock(). A socket needs to be assigned to the BIO before it can be used. - 'shutdown', this flag indicates if the underlying - comunication primative being used should be closed/freed + communication primitive being used should be closed/freed when the BIO is closed. - 'flags' is used to hold extra state. It is primarily used to hold information about why a non-blocking operation @@ -1799,7 +1799,7 @@ int BN_set_word(BIGNUM *a, unsigned long w); unsigned long BN_get_word(BIGNUM *a); Returns 'a' in an unsigned long. Not remarkably, often 'a' will - be biger than a word, in which case 0xffffffffL is returned. + be bigger than a word, in which case 0xffffffffL is returned. Word Operations These functions are much more efficient that the normal bignum arithmetic @@ -2058,7 +2058,7 @@ Now you will notice that macros like PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \ (char *)x, NULL,NULL,0,NULL) Don't do encryption normally. If you want to PEM encrypt your X509 structure, -either just call PEM_ASN1_write directly or just define you own +either just call PEM_ASN1_write directly or just define your own macro variant. As you can see, this macro just sets all encryption related parameters to NULL. @@ -5566,7 +5566,7 @@ These 2 functions create and destroy SSL_CTX structures The SSL_CTX has a session_cache_mode which is by default, in SSL_SESS_CACHE_SERVER mode. What this means is that the library -will automatically add new session-id's to the cache apon sucsessful +will automatically add new session-id's to the cache upon successful SSL_accept() calls. If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added to the cache. @@ -5580,12 +5580,12 @@ SSL_SESS_NO_CACHE_BOTH - Either SSL_accept() or SSL_connect(). If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are not automatically removed each 255, SSL_connect()s or SSL_accept()s. -By default, apon every 255 successful SSL_connect() or SSL_accept()s, +By default, upon every 255 successful SSL_connect() or SSL_accept()s, the cache is flush. Please note that this could be expensive on a heavily loaded SSL server, in which case, turn this off and clear the cache of old entries 'manually' (with one of the functions listed below) every few hours. Perhaps I should up this number, it is hard -to say. Remember, the '255' new calls is just a mechanims to get called +to say. Remember, the '255' new calls is just a mechanism to get called every now and then, in theory at most 255 new session-id's will have been added but if 100 are added every minute, you would still have 500 in the cache before any would start being flushed (assuming a 3 minute @@ -5628,10 +5628,10 @@ if copy is 1. Otherwise, the reference count is not modified. void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback. -These callbacks are basically indended to be used by processes to +These callbacks are basically intended to be used by processes to send their session-id's to other processes. I currently have not implemented -non-blocking semantics for these callbacks, it is upto the appication -to make the callbacks effiecent if they require blocking (perhaps +non-blocking semantics for these callbacks, it is upto the application +to make the callbacks efficient if they require blocking (perhaps by 'saving' them and then 'posting them' when control returns from the SSL_accept(). @@ -6589,7 +6589,7 @@ This information can be used to recall the functions when the 'error' condition has dissapeared. After the connection has been made, information can be retrived about the -SSL session and the session-id values that have been decided apon. +SSL session and the session-id values that have been decided upon. The 'peer' certificate can be retrieved. The session-id values include diff --git a/openssl/doc/standards.txt b/openssl/doc/standards.txt index a5ce778f8..7bada8d35 100644 --- a/openssl/doc/standards.txt +++ b/openssl/doc/standards.txt @@ -69,6 +69,10 @@ PKCS#12: Personal Information Exchange Syntax Standard, version 1.0. 3174 US Secure Hash Algorithm 1 (SHA1). D. Eastlake 3rd, P. Jones. September 2001. (Format: TXT=35525 bytes) (Status: INFORMATIONAL) +3161 Internet X.509 Public Key Infrastructure, Time-Stamp Protocol (TSP) + C. Adams, P. Cain, D. Pinkas, R. Zuccherato. August 2001 + (Status: PROPOSED STANDARD) + 3268 Advanced Encryption Standard (AES) Ciphersuites for Transport Layer Security (TLS). P. Chown. June 2002. (Format: TXT=13530 bytes) (Status: PROPOSED STANDARD) -- cgit v1.2.3