diff options
Diffstat (limited to 'openssl/doc')
127 files changed, 7499 insertions, 520 deletions
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<string>, B<file> or both using -ASN1_generate_nconf() format. If B<file> only is present then the string -is obtained from the default section using the name B<asn1>. 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<out> option. +L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. If B<file> only is +present then the string is obtained from the default section using the name +B<asn1>. 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<out> 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<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> + =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<x509_extensions> 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<x509v3_config(5)|x509v3_config(5)> 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<ca> 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<not> 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<x509v3_config(5)|x509v3_config(5)> 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<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, -L<config(5)|config(5)> +L<config(5)|config(5)>, L<x509v3_config(5)|x509v3_config(5)> =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<openssl> B<ciphers> [B<-v>] +[B<-V>] [B<-ssl2>] [B<-ssl3>] [B<-tls1>] @@ -15,7 +16,7 @@ B<openssl> B<ciphers> =head1 DESCRIPTION -The B<cipherlist> command converts OpenSSL cipher lists into ordered +The B<ciphers> 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<DEFAULT> -the default cipher list. This is determined at compile time and is normally -B<AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH>. 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<ALL:!aNULL:!eNULL>. This must be the first cipher string specified. =item B<COMPLEMENTOFDEFAULT> @@ -116,7 +121,8 @@ not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary). =item B<ALL> -all ciphers suites except the B<eNULL> ciphers which must be explicitly enabled. +all cipher suites except the B<eNULL> ciphers which must be explicitly enabled; +as of OpenSSL, the B<ALL> cipher suites are reasonably ordered by default =item B<COMPLEMENTOFALL> @@ -245,6 +251,33 @@ cipher suites using MD5. cipher suites using SHA1. +=item B<aGOST> + +cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction +(needs an engine supporting GOST algorithms). + +=item B<aGOST01> + +cipher suites using GOST R 34.10-2001 authentication. + +=item B<aGOST94> + +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<kGOST> + +cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357. + +=item B<GOST94> + +cipher suites, using HMAC based on GOST R 34.11-94. + +=item B<GOST89MAC> + +cipher suites using GOST 28147-89 MAC B<instead of> 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<ccgost> 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<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)> =head1 HISTORY -The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options were -added in version 0.9.7. +The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options +for cipherlist strings were added in OpenSSL 0.9.7. +The B<-V> option for the B<ciphers> 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<openssl> B<cms> +[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<cert.pem...>] +[B<-to addr>] +[B<-from addr>] +[B<-subject subj>] +[cert.pem]... + +=head1 DESCRIPTION + +The B<cms> 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 <B>EnvelopedData<B>. + +=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<Data> type. + +=item B<-data_out> + +B<Data> type and output the content. + +=item B<-digest_create> + +Create a CMS B<DigestedData> type. + +=item B<-digest_verify> + +Verify a CMS B<DigestedData> type and output the content. + +=item B<-compress> + +Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> +support for this option to work, otherwise it will output an error. + +=item B<-uncompress> + +Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be +compiled with B<zlib> 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<EncrytedData> type and output the content. + +=item B<-sign_receipt> + +Generate and output a signed receipt for the supplied message. The input +message B<must> 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<receipt>. The input message B<must> +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<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> +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<SMIME> which writes an S/MIME format message. B<PEM> and B<DER> +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<SMIME> 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<x509 -hash>) 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<B<enc>|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<file>. + +=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<must> 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<must> 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<KEKRecipientInfo> type. + +=item B<-secretkeyid id> + +the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type. +This option B<must> be present if the B<-secretkey> option is used with +B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the +relevant key if it is not supplied then an attempt is used to decrypt any +B<KEKRecipientInfo> structures. + +=item B<-econtent_type type> + +set the encapsulated content type to B<type> if not supplied the B<Data> type +is used. The B<type> 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<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. + +=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<RAND_egd(3)|RAND_egd(3)>). +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<cert.pem...> + +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<B<verify>|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<smime> utility can only process the older B<PKCS#7> format. The B<cms> +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<smime> 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<openssl> B<dgst> [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<dgst> command. + +=item B<-engine id> + +Use engine B<id> 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<arg> @@ -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<gost-mac> algorithm, +supported by B<ccgost> 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<HMAC> and B<gost-mac>: + +=over 8 + +=item B<key:string> + +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<hexkey:string> + +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 B<get_dh>I<numbits>B<()> function. =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<dhparam> 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<dsa> 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<dsaparam> 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<ec> 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<ecparam> 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<openssl enc -ciphername> [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<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. =item B<-salt> -use a salt in the key derivation routines. This option should B<ALWAYS> -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<SHOULD NOT> 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<filename>. 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<openssl ciphername> or -B<openssl enc -ciphername>. +B<openssl enc -ciphername>. 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<enc> command run with +unsupported options (for example B<openssl enc -help>) 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<gendsa> 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<openssl> B<genpkey> +[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<genpkey> 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<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. + +=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<des3>. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<genpkey> +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<opt> to B<value>. The precise set of +options supported depends on the public key algorithm used and its +implementation. See B<KEY GENERATION OPTIONS> 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<rsa_keygen_bits:numbits> + +The number of bits in the generated key. If not specified 1024 is used. + +=item B<rsa_keygen_pubexp:value> + +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<dsa_paramgen_bits:numbits> + +The number of bits in the generated parameters. If not specified 1024 is used. + +=head1 DH PARAMETER GENERATION OPTIONS + +=over 4 + +=item B<dh_paramgen_prime_len:numbits> + +The number of bits in the prime parameter B<p>. + +=item B<dh_paramgen_generator:value> + +The value to use for the generator B<g>. + +=back + +=head1 EC PARAMETER GENERATION OPTIONS + +=over 4 + +=item B<ec_paramgen_curve:curve> + +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<paramset:name> + +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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<genrsa> 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<openssl> B<ocsp> [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<notBefore> f is checked to see it is not older than B<age> 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<command> [ I<command_opts> ] [ I<command_args> ] -B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> ] +B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> | B<list-cipher-algorithms> | B<list-message-digest-algorithms> | B<list-public-key-algorithms>] B<openssl> B<no->I<XXX> [ I<arbitrary options> ] @@ -26,12 +26,14 @@ The B<openssl> program is a command line tool for using the various cryptography functions of OpenSSL's B<crypto> 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<list-cipher-commands> 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<openssl> utility. +The pseudo-commands B<list-cipher-algorithms> and +B<list-message-digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as: + + from => to + +The pseudo-command B<list-public-key-algorithms> lists all supported public +key algorithms. + The pseudo-command B<no->I<XXX> tests whether a command of the specified name is available. If no command named I<XXX> exists, it returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1 @@ -71,6 +81,10 @@ Certificate Authority (CA) Management. Cipher Suite Description Determination. +=item L<B<cms>|cms(1)> + +CMS (Cryptographic Message Syntax) utility + =item L<B<crl>|crl(1)> Certificate Revocation List (CRL) Management. @@ -88,25 +102,40 @@ Message Digest Calculation. Diffie-Hellman Parameter Management. Obsoleted by L<B<dhparam>|dhparam(1)>. +=item L<B<dhparam>|dhparam(1)> + +Generation and Management of Diffie-Hellman Parameters. Superseded by +L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)> + + =item L<B<dsa>|dsa(1)> DSA Data Management. =item L<B<dsaparam>|dsaparam(1)> -DSA Parameter Generation. +DSA Parameter Generation and Management. Superseded by +L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)> + +=item L<B<ec>|ec(1)> + +EC (Elliptic curve) key processing + +=item L<B<ecparam>|ecparam(1)> + +EC parameter manipulation and generation =item L<B<enc>|enc(1)> Encoding with Ciphers. -=item L<B<errstr>|errstr(1)> +=item L<B<engine>|engine(1)> -Error Number to Error String Conversion. +Engine (loadble module) information and manipulation. -=item L<B<dhparam>|dhparam(1)> +=item L<B<errstr>|errstr(1)> -Generation and Management of Diffie-Hellman Parameters. +Error Number to Error String Conversion. =item B<gendh> @@ -115,11 +144,20 @@ Obsoleted by L<B<dhparam>|dhparam(1)>. =item L<B<gendsa>|gendsa(1)> -Generation of DSA Parameters. +Generation of DSA Private Key from Parameters. Superseded by +L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)> + +=item L<B<genpkey>|genpkey(1)> + +Generation of Private Key or Parameters. =item L<B<genrsa>|genrsa(1)> -Generation of RSA Parameters. +Generation of RSA Private Key. Superceded by L<B<genpkey>|genpkey(1)>. + +=item L<B<nseq>|nseq(1)> + +Create or examine a netscape certificate sequence =item L<B<ocsp>|ocsp(1)> @@ -137,21 +175,35 @@ PKCS#12 Data Management. PKCS#7 Data Management. +=item L<B<pkey>|pkey(1)> + +Public and private key management. + +=item L<B<pkeyparam>|pkeyparam(1)> + +Public key algorithm parameter management. + +=item L<B<pkeyutl>|pkeyutl(1)> + +Public key algorithm cryptographic operation utility. + =item L<B<rand>|rand(1)> Generate pseudo-random bytes. =item L<B<req>|req(1)> -X.509 Certificate Signing Request (CSR) Management. +PKCS#10 X.509 Certificate Signing Request (CSR) Management. =item L<B<rsa>|rsa(1)> -RSA Data Management. +RSA key management. + =item L<B<rsautl>|rsautl(1)> -RSA utility for signing, verification, encryption, and decryption. +RSA utility for signing, verification, encryption, and decryption. Superseded +by L<B<pkeyutl>|pkeyutl(1)> =item L<B<s_client>|s_client(1)> @@ -185,6 +237,14 @@ S/MIME mail processing. Algorithm Speed Measurement. +=item L<B<spkac>|spkac(1)> + +SPKAC printing and generating utility + +=item L<B<ts>|ts(1)> + +Time Stamping Authority tool (client/server) + =item L<B<verify>|verify(1)> X.509 Certificate Verification. @@ -227,6 +287,8 @@ SHA Digest SHA-1 Digest +=back + =item B<sha224> 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<asn1parse(1)|asn1parse(1)>, L<ca(1)|ca(1)>, L<config(5)|config(5)>, L<crl(1)|crl(1)>, L<crl2pkcs7(1)|crl2pkcs7(1)>, L<dgst(1)|dgst(1)>, L<dhparam(1)|dhparam(1)>, L<dsa(1)|dsa(1)>, L<dsaparam(1)|dsaparam(1)>, -L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, +L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, L<genpkey(1)|genpkey(1)>, L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>, L<passwd(1)|passwd(1)>, L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>, @@ -348,12 +408,13 @@ L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>, L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>, L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>, -L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)> +L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)>, L<x509v3_config(5)|x509v3_config(5)> =head1 HISTORY The openssl(1) document appeared in OpenSSL 0.9.2. The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3; +The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0; the B<no->I<XXX> 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<openssl> B<pkcs12> [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<arg> see the B<PASS PHRASE ARGUMENTS> section in +the PKCS#12 file (i.e. input file) password source. For more information about +the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. =item B<-passout arg> -pass phrase source to encrypt any outputed private keys with. For more information -about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in -L<openssl(1)|openssl(1)>. +pass phrase source to encrypt any outputed private keys with. For more +information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section +in L<openssl(1)|openssl(1)>. =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<NOTES> section for more information. +certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name +can be used (see B<NOTES> section for more information). If a a cipher name +(as output by the B<list-cipher-algorithms> 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<x509 -hash>) should be +linked to each certificate. + +=item B<-CSP name> + +write B<name> 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<pkcs7> 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<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<pkcs8> 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<openssl> B<pkey> +[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<pkey> 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<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. + +=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<not> be the same as the input +filename. + +=item B<-passout password> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. + +=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<des3>. + +=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<id> string) will cause B<pkey> +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<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>, +L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)> + +=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<openssl> B<pkeyparam> +[B<-in filename>] +[B<-out filename>] +[B<-text>] +[B<-noout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<pkey> 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<id> string) will cause B<pkeyparam> +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<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>, +L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)> + +=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<openssl> B<pkeyutl> +[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<pkeyutl> 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<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. + + +=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<id> string) will cause B<pkeyutl> +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<digest:alg> option +which specifies the digest in use for sign, verify and verifyrecover operations. +The value B<alg> should represent a digest name as used in the +EVP_get_digestbyname() function for example B<sha1>. + +=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<rsa_padding_mode:mode> + +This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for +PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep> +for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> 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<DigestInfo> structure. If a +digest is set then the a B<DigestInfo> structure is used and its the length +must correspond to the digest type. + +For B<oeap> mode only encryption and decryption is supported. + +For B<x931> 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<pss> mode only sign and verify are supported and the digest type must be +specified. + +=item B<rsa_pss_saltlen:len> + +For B<pss> 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<PSS> block +structure. + +=back + +=head1 DSA ALGORITHM + +The DSA algorithm supports signing and verification operations only. Currently +there are no additional options other than B<digest>. 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<digest>. 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<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)> +L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> 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<openssl> B<req> [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<openssl> B<req> [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<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 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</type0=value0/type1=value1/type2=...>, +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<rsa:nbits>, where +key. The argument takes one of several forms. B<rsa:nbits>, where B<nbits> is the number of bits, generates an RSA key B<nbits> -in size. B<dsa:filename> generates a DSA key using the parameters -in the file B<filename>. +in size. If B<nbits> 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<genpkey -genparam> command +or and X.509 certificate for a key with approriate algorithm. + +B<param:file> generates a key using the parameter file or certificate B<file>, +the algorithm is determined by the parameters. B<algname:file> use algorithm +B<algname> and parameter file B<file>: the two algorithms must match or an +error occurs. B<algname> just uses algorithm B<algname>, and parameters, +if neccessary should be specified via B<-pkeyopt> parameter. + +B<dsa:filename> generates a DSA key using the parameters +in the file B<filename>. B<ec:filename> generates EC key (usable both with +ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R +34.10-2001 key (requires B<ccgost> engine configured in the configuration +file). If just B<gost2001> 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<opt> to B<value>. The precise set of +options supported depends on the public key algorithm used and its +implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> 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<option> argument can be a single option or multiple options separated by commas. Alternatively the B<-nameopt> switch may be used more than once to set multiple options. See the L<x509(1)|x509(1)> manual page for details. +=item B<-reqopt> + +customise the output format used with B<-text>. The B<option> argument can be +a single option or multiple options separated by commas. + +See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)> +command. + + =item B<-asn1-kludge> by default the B<req> command outputs certificate requests containing @@ -242,6 +297,10 @@ B<SET OF> whereas the correct form does. It should be noted that very few CAs still require the use of this option. +=item B<-no-asn1-kludge> + +Reverses effect of B<-asn1-kludge> + =item B<-newhdr> Adds the word B<NEW> to the PEM file header and footer lines on the outputed @@ -257,11 +316,16 @@ print extra details about the operations being performed. =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<req> 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<-keygen_engine id> + +specifies an engine (by its unique B<id> string) which would be used +for key generation operations. + =back =head1 CONFIGURATION FILE FORMAT @@ -344,7 +408,9 @@ problems with BMPStrings and UTF8Strings: in particular Netscape. this specifies the configuration file section containing a list of extensions to add to the certificate request. It can be overridden -by the B<-reqexts> command line switch. +by the B<-reqexts> command line switch. See the +L<x509v3_config(5)|x509v3_config(5)> manual page for details of the +extension section format. =item B<x509_extensions> @@ -606,6 +672,7 @@ address in subjectAltName should be input by the user. =head1 SEE ALSO L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)> +L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>, +L<x509v3_config(5)|x509v3_config(5)> =cut diff --git a/openssl/doc/apps/rsa.pod b/openssl/doc/apps/rsa.pod index 4d7640995..69b2bef82 100644 --- a/openssl/doc/apps/rsa.pod +++ b/openssl/doc/apps/rsa.pod @@ -120,7 +120,7 @@ the input is a public key. =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<rsa> 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/s_client.pod b/openssl/doc/apps/s_client.pod index c44d357cf..4ebf7b585 100644 --- a/openssl/doc/apps/s_client.pod +++ b/openssl/doc/apps/s_client.pod @@ -101,6 +101,11 @@ also used when building the client certificate chain. A file containing trusted certificates to use during server authentication and to use when attempting to build the client certificate chain. +=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<B<verify>|verify(1)> manual page for details. + =item B<-reconnect> reconnects to the same server 5 times using the same session ID, this can @@ -161,6 +166,16 @@ input. inhibit printing of session and certificate information. This implicitly turns on B<-ign_eof> as well. +=item B<-psk_identity identity> + +Use the PSK identity B<identity> when using a PSK cipher suite. + +=item B<-psk key> + +Use the PSK key B<key> when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. + =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> these options disable the use of certain SSL or TLS protocols. By default @@ -192,14 +207,11 @@ supported keywords are "smtp", "pop3", "imap", and "ftp". =item B<-tlsextdebug> -print out a hex dump of any TLS extensions received from the server. Note: this -option is only available if extension support is explicitly enabled at compile -time +print out a hex dump of any TLS extensions received from the server. =item B<-no_ticket> -disable RFC4507bis session ticket support. Note: this option is only available -if extension support is explicitly enabled at compile time +disable RFC4507bis session ticket support. =item B<-sess_out filename> @@ -212,7 +224,7 @@ connection from this session. =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<s_client> +specifying an engine (by its unique B<id> string) will cause B<s_client> 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. @@ -274,9 +286,6 @@ Since the SSLv23 client hello cannot include compression methods or extensions these will only be supported if its use is disabled, for example by using the B<-no_sslv2> option. -TLS extensions are only supported in OpenSSL 0.9.8 if they are explictly -enabled at compile time using for example the B<enable-tlsext> switch. - =head1 BUGS Because this program has a lot of options and also because some of diff --git a/openssl/doc/apps/s_server.pod b/openssl/doc/apps/s_server.pod index fdcc170e2..3e503e17e 100644 --- a/openssl/doc/apps/s_server.pod +++ b/openssl/doc/apps/s_server.pod @@ -191,6 +191,16 @@ this option translated a line feed from the terminal into CR+LF. inhibit printing of session and certificate information. +=item B<-psk_hint hint> + +Use the PSK identity hint B<hint> when using a PSK cipher suite. + +=item B<-psk key> + +Use the PSK key B<key> when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. + =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> these options disable the use of certain SSL or TLS protocols. By default @@ -246,7 +256,7 @@ are part of the HTTP response line and headers must end with CRLF). =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<s_server> +specifying an engine (by its unique B<id> string) will cause B<s_server> 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. @@ -325,9 +335,6 @@ mean any CA is acceptable. This is useful for debugging purposes. The session parameters can printed out using the B<sess_id> program. -TLS extensions are only supported in OpenSSL 0.9.8 if they are explictly -enabled at compile time using for example the B<enable-tlsext> switch. - =head1 BUGS Because this program has a lot of options and also because some of diff --git a/openssl/doc/apps/smime.pod b/openssl/doc/apps/smime.pod index caf2d2689..42c0733bc 100644 --- a/openssl/doc/apps/smime.pod +++ b/openssl/doc/apps/smime.pod @@ -10,19 +10,10 @@ B<openssl> B<smime> [B<-encrypt>] [B<-decrypt>] [B<-sign>] +[B<-resign>] [B<-verify>] [B<-pk7out>] -[B<-des>] -[B<-des3>] -[B<-rc2-40>] -[B<-rc2-64>] -[B<-rc2-128>] -[B<-aes128>] -[B<-aes192>] -[B<-aes256>] -[B<-camellia128>] -[B<-camellia192>] -[B<-camellia256>] +[B<-[cipher]>] [B<-in file>] [B<-certfile file>] [B<-signer file>] @@ -37,7 +28,11 @@ B<openssl> B<smime> [B<-from ad>] [B<-subject s>] [B<-text>] +[B<-indef>] +[B<-noindef>] +[B<-stream>] [B<-rand file(s)>] +[B<-md digest>] [cert.pem]... =head1 DESCRIPTION @@ -47,7 +42,7 @@ verify S/MIME messages. =head1 COMMAND OPTIONS -There are five operation options that set the type of operation to be performed. +There are six 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 @@ -78,6 +73,10 @@ the signed data. Both clear text and opaque signing is supported. takes an input message and writes out a PEM encoded PKCS#7 structure. +=item B<-resign> + +resign a message: take an existing message and one or more new signers. + =item B<-in filename> the input message to be encrypted or signed or the MIME message to @@ -106,6 +105,21 @@ instead. This currently only affects the output format of the PKCS#7 structure, if no PKCS#7 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<SMIME> 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 @@ -132,11 +146,20 @@ B<-verify>. This directory must be a standard certificate directory: that is a hash of each subject name (using B<x509 -hash>) should be linked to each certificate. -=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256> +=item B<-md digest> -the encryption algorithm to use. DES (56 bits), triple DES (168 bits), -40, 64 or 128 bit RC2, 128, 192 or 256 bit AES, or 128, 192 or 256 bit Camellia respectively. If not -specified 40 bit RC2 is used. Only used with B<-encrypt>. +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 DES (56 bits) - B<-des>, +triple DES (168 bits) - B<-des3>, +EVP_get_cipherbyname() function) can also be used preceded by a dash, for +example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers +supported by your version of OpenSSL. + +If not specified 40 bit RC2 is used. Only used with B<-encrypt>. =item B<-nointern> @@ -193,9 +216,10 @@ the signers certificates. The certificates should be in PEM format. =item B<-signer file> -the signers certificate when signing a message. If a message is -being verified then the signers certificates will be written to this -file if the verification was successful. +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> @@ -207,7 +231,8 @@ must match one of the recipients of the message or an error occurs. 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. +the B<-recip> or B<-signer> file. When signing this option can be used +multiple times to specify successive keys. =item B<-passin arg> @@ -234,6 +259,11 @@ 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 options of certificate chain verification. See +L<B<verify>|verify(1)> manual page for details. + =back =head1 NOTES @@ -261,6 +291,19 @@ The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 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 PKCS#7 structure the encoding +remains DER. + =head1 EXIT CODES =over 4 @@ -300,7 +343,7 @@ Create a cleartext signed message: openssl smime -sign -in message.txt -text -out mail.msg \ -signer mycert.pem -Create and opaque signed message +Create an opaque signed message openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ -signer mycert.pem @@ -311,6 +354,11 @@ read the private key from another file: openssl smime -sign -in in.txt -text -out mail.msg \ -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem +Create a signed message with two signers: + + openssl smime -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem -signer othercert.pem + Send a signed message under Unix directly to sendmail, including headers: openssl smime -sign -in in.txt -text -signer mycert.pem \ @@ -334,8 +382,8 @@ Sign and encrypt mail: -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. +Note: the encryption command does not include the B<-text> option because the +message being encrypted already has MIME headers. Decrypt mail: @@ -361,16 +409,22 @@ Create an encrypted message using 128 bit Camellia: openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem +Add a signer to an existing message: + + openssl smime -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 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. +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. +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 @@ -382,4 +436,10 @@ No revocation checking is done on the signer's certificate. The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 structures may cause parsing errors. +=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/speed.pod b/openssl/doc/apps/speed.pod index 0dcdba873..1cd1998d1 100644 --- a/openssl/doc/apps/speed.pod +++ b/openssl/doc/apps/speed.pod @@ -44,7 +44,7 @@ This command is used to test the performance of cryptographic algorithms. =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<speed> +specifying an engine (by its unique B<id> string) will cause B<speed> 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/spkac.pod b/openssl/doc/apps/spkac.pod index c3f1ff9c6..97fb80e40 100644 --- a/openssl/doc/apps/spkac.pod +++ b/openssl/doc/apps/spkac.pod @@ -81,7 +81,7 @@ verifies the digital signature on the supplied SPKAC. =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<spkac> 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/ts.pod b/openssl/doc/apps/ts.pod new file mode 100644 index 000000000..7fb6caa96 --- /dev/null +++ b/openssl/doc/apps/ts.pod @@ -0,0 +1,594 @@ +=pod + +=head1 NAME + +ts - Time Stamping Authority tool (client/server) + +=head1 SYNOPSIS + +B<openssl> B<ts> +B<-query> +[B<-rand> file:file...] +[B<-config> configfile] +[B<-data> file_to_hash] +[B<-digest> digest_bytes] +[B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>] +[B<-policy> object_id] +[B<-no_nonce>] +[B<-cert>] +[B<-in> request.tsq] +[B<-out> request.tsq] +[B<-text>] + +B<openssl> B<ts> +B<-reply> +[B<-config> configfile] +[B<-section> tsa_section] +[B<-queryfile> request.tsq] +[B<-passin> password_src] +[B<-signer> tsa_cert.pem] +[B<-inkey> private.pem] +[B<-chain> certs_file.pem] +[B<-policy> object_id] +[B<-in> response.tsr] +[B<-token_in>] +[B<-out> response.tsr] +[B<-token_out>] +[B<-text>] +[B<-engine> id] + +B<openssl> B<ts> +B<-verify> +[B<-data> file_to_hash] +[B<-digest> digest_bytes] +[B<-queryfile> request.tsq] +[B<-in> response.tsr] +[B<-token_in>] +[B<-CApath> trusted_cert_path] +[B<-CAfile> trusted_certs.pem] +[B<-untrusted> cert_file.pem] + +=head1 DESCRIPTION + +The B<ts> command is a basic Time Stamping Authority (TSA) client and server +application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A +TSA can be part of a PKI deployment and its role is to provide long +term proof of the existence of a certain datum before a particular +time. Here is a brief description of the protocol: + +=over 4 + +=item 1. + +The TSA client computes a one-way hash value for a data file and sends +the hash to the TSA. + +=item 2. + +The TSA attaches the current date and time to the received hash value, +signs them and sends the time stamp token back to the client. By +creating this token the TSA certifies the existence of the original +data file at the time of response generation. + +=item 3. + +The TSA client receives the time stamp token and verifies the +signature on it. It also checks if the token contains the same hash +value that it had sent to the TSA. + +=back + +There is one DER encoded protocol data unit defined for transporting a time +stamp request to the TSA and one for sending the time stamp response +back to the client. The B<ts> command has three main functions: +creating a time stamp request based on a data file, +creating a time stamp response based on a request, verifying if a +response corresponds to a particular request or a data file. + +There is no support for sending the requests/responses automatically +over HTTP or TCP yet as suggested in RFC 3161. The users must send the +requests either by ftp or e-mail. + +=head1 OPTIONS + +=head2 Time Stamp Request generation + +The B<-query> switch can be used for creating and printing a time stamp +request with the following options: + +=over 4 + +=item B<-rand> file:file... + +The files containing random data for seeding the random number +generator. Multiple files can be specified, the separator is B<;> for +MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) + +=item B<-config> configfile + +The configuration file to use, this option overrides the +B<OPENSSL_CONF> environment variable. Only the OID section +of the config file is used with the B<-query> command. (Optional) + +=item B<-data> file_to_hash + +The data file for which the time stamp request needs to be +created. stdin is the default if neither the B<-data> nor the B<-digest> +parameter is specified. (Optional) + +=item B<-digest> digest_bytes + +It is possible to specify the message imprint explicitly without the data +file. The imprint must be specified in a hexadecimal format, two characters +per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or +1AF601...). The number of bytes must match the message digest algorithm +in use. (Optional) + +=item B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...> + +The message digest to apply to the data file, it supports all the message +digest algorithms that are supported by the openssl B<dgst> command. +The default is SHA-1. (Optional) + +=item B<-policy> object_id + +The policy that the client expects the TSA to use for creating the +time stamp token. Either the dotted OID notation or OID names defined +in the config file can be used. If no policy is requested the TSA will +use its own default policy. (Optional) + +=item B<-no_nonce> + +No nonce is specified in the request if this option is +given. Otherwise a 64 bit long pseudo-random none is +included in the request. It is recommended to use nonce to +protect against replay-attacks. (Optional) + +=item B<-cert> + +The TSA is expected to include its signing certificate in the +response. (Optional) + +=item B<-in> request.tsq + +This option specifies a previously created time stamp request in DER +format that will be printed into the output file. Useful when you need +to examine the content of a request in human-readable + +format. (Optional) + +=item B<-out> request.tsq + +Name of the output file to which the request will be written. Default +is stdout. (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=back + +=head2 Time Stamp Response generation + +A time stamp response (TimeStampResp) consists of a response status +and the time stamp token itself (ContentInfo), if the token generation was +successful. The B<-reply> command is for creating a time stamp +response or time stamp token based on a request and printing the +response/token in human-readable format. If B<-token_out> is not +specified the output is always a time stamp response (TimeStampResp), +otherwise it is a time stamp token (ContentInfo). + +=over 4 + +=item B<-config> configfile + +The configuration file to use, this option overrides the +B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE +OPTIONS> for configurable variables. (Optional) + +=item B<-section> tsa_section + +The name of the config file section conatining the settings for the +response generation. If not specified the default TSA section is +used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional) + +=item B<-queryfile> request.tsq + +The name of the file containing a DER encoded time stamp request. (Optional) + +=item B<-passin> password_src + +Specifies the password source for the private key of the TSA. See +B<PASS PHRASE ARGUMENTS> in L<openssl(1)|openssl(1)>. (Optional) + +=item B<-signer> tsa_cert.pem + +The signer certificate of the TSA in PEM format. The TSA signing +certificate must have exactly one extended key usage assigned to it: +timeStamping. The extended key usage must also be critical, otherwise +the certificate is going to be refused. Overrides the B<signer_cert> +variable of the config file. (Optional) + +=item B<-inkey> private.pem + +The signer private key of the TSA in PEM format. Overrides the +B<signer_key> config file option. (Optional) + +=item B<-chain> certs_file.pem + +The collection of certificates in PEM format that will all +be included in the response in addition to the signer certificate if +the B<-cert> option was used for the request. This file is supposed to +contain the certificate chain for the signer certificate from its +issuer upwards. The B<-reply> command does not build a certificate +chain automatically. (Optional) + +=item B<-policy> object_id + +The default policy to use for the response unless the client +explicitly requires a particular TSA policy. The OID can be specified +either in dotted notation or with its name. Overrides the +B<default_policy> config file option. (Optional) + +=item B<-in> response.tsr + +Specifies a previously created time stamp response or time stamp token +(if B<-token_in> is also specified) in DER format that will be written +to the output file. This option does not require a request, it is +useful e.g. when you need to examine the content of a response or +token or you want to extract the time stamp token from a response. If +the input is a token and the output is a time stamp response a default +'granted' status info is added to the token. (Optional) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-out> response.tsr + +The response is written to this file. The format and content of the +file depends on other options (see B<-text>, B<-token_out>). The default is +stdout. (Optional) + +=item B<-token_out> + +The output is a time stamp token (ContentInfo) instead of time stamp +response (TimeStampResp). (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=item B<-engine> id + +Specifying an engine (by its unique B<id> string) will cause B<ts> +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. Default is builtin. (Optional) + +=back + +=head2 Time Stamp Response verification + +The B<-verify> command is for verifying if a time stamp response or time +stamp token is valid and matches a particular time stamp request or +data file. The B<-verify> command does not use the configuration file. + +=over 4 + +=item B<-data> file_to_hash + +The response or token must be verified against file_to_hash. The file +is hashed with the message digest algorithm specified in the token. +The B<-digest> and B<-queryfile> options must not be specified with this one. +(Optional) + +=item B<-digest> digest_bytes + +The response or token must be verified against the message digest specified +with this option. The number of bytes must match the message digest algorithm +specified in the token. The B<-data> and B<-queryfile> options must not be +specified with this one. (Optional) + +=item B<-queryfile> request.tsq + +The original time stamp request in DER format. The B<-data> and B<-digest> +options must not be specified with this one. (Optional) + +=item B<-in> response.tsr + +The time stamp response that needs to be verified in DER format. (Mandatory) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-CApath> trusted_cert_path + +The name of the directory containing the trused CA certificates of the +client. See the similar option of L<verify(1)|verify(1)> for additional +details. Either this option or B<-CAfile> must be specified. (Optional) + + +=item B<-CAfile> trusted_certs.pem + +The name of the file containing a set of trusted self-signed CA +certificates in PEM format. See the similar option of +L<verify(1)|verify(1)> for additional details. Either this option +or B<-CApath> must be specified. +(Optional) + +=item B<-untrusted> cert_file.pem + +Set of additional untrusted certificates in PEM format which may be +needed when building the certificate chain for the TSA's signing +certificate. This file must contain the TSA signing certificate and +all intermediate CA certificates unless the response includes them. +(Optional) + +=back + +=head1 CONFIGURATION FILE OPTIONS + +The B<-query> and B<-reply> commands make use of a configuration file +defined by the B<OPENSSL_CONF> environment variable. See L<config(5)|config(5)> +for a general description of the syntax of the config file. The +B<-query> command uses only the symbolic OID names section +and it can work without it. However, the B<-reply> command needs the +config file for its operation. + +When there is a command line switch equivalent of a variable the +switch always overrides the settings in the config file. + +=over 4 + +=item B<tsa> section, B<default_tsa> + +This is the main section and it specifies the name of another section +that contains all the options for the B<-reply> command. This default +section can be overriden with the B<-section> command line switch. (Optional) + +=item B<oid_file> + +See L<ca(1)|ca(1)> for description. (Optional) + +=item B<oid_section> + +See L<ca(1)|ca(1)> for description. (Optional) + +=item B<RANDFILE> + +See L<ca(1)|ca(1)> for description. (Optional) + +=item B<serial> + +The name of the file containing the hexadecimal serial number of the +last time stamp response created. This number is incremented by 1 for +each response. If the file does not exist at the time of response +generation a new file is created with serial number 1. (Mandatory) + +=item B<crypto_device> + +Specifies the OpenSSL engine that will be set as the default for +all available algorithms. The default value is builtin, you can specify +any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM). +(Optional) + +=item B<signer_cert> + +TSA signing certificate in PEM format. The same as the B<-signer> +command line option. (Optional) + +=item B<certs> + +A file containing a set of PEM encoded certificates that need to be +included in the response. The same as the B<-chain> command line +option. (Optional) + +=item B<signer_key> + +The private key of the TSA in PEM format. The same as the B<-inkey> +command line option. (Optional) + +=item B<default_policy> + +The default policy to use when the request does not mandate any +policy. The same as the B<-policy> command line option. (Optional) + +=item B<other_policies> + +Comma separated list of policies that are also acceptable by the TSA +and used only if the request explicitly specifies one of them. (Optional) + +=item B<digests> + +The list of message digest algorithms that the TSA accepts. At least +one algorithm must be specified. (Mandatory) + +=item B<accuracy> + +The accuracy of the time source of the TSA in seconds, milliseconds +and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of +the components is missing zero is assumed for that field. (Optional) + +=item B<clock_precision_digits> + +Specifies the maximum number of digits, which represent the fraction of +seconds, that need to be included in the time field. The trailing zeroes +must be removed from the time, so there might actually be fewer digits, +or no fraction of seconds at all. Supported only on UNIX platforms. +The maximum value is 6, default is 0. +(Optional) + +=item B<ordering> + +If this option is yes the responses generated by this TSA can always +be ordered, even if the time difference between two responses is less +than the sum of their accuracies. Default is no. (Optional) + +=item B<tsa_name> + +Set this option to yes if the subject name of the TSA must be included in +the TSA name field of the response. Default is no. (Optional) + +=item B<ess_cert_id_chain> + +The SignedData objects created by the TSA always contain the +certificate identifier of the signing certificate in a signed +attribute (see RFC 2634, Enhanced Security Services). If this option +is set to yes and either the B<certs> variable or the B<-chain> option +is specified then the certificate identifiers of the chain will also +be included in the SigningCertificate signed attribute. If this +variable is set to no, only the signing certificate identifier is +included. Default is no. (Optional) + +=back + +=head1 ENVIRONMENT VARIABLES + +B<OPENSSL_CONF> contains the path of the configuration file and can be +overriden by the B<-config> command line option. + +=head1 EXAMPLES + +All the examples below presume that B<OPENSSL_CONF> is set to a proper +configuration file, e.g. the example configuration file +openssl/apps/openssl.cnf will do. + +=head2 Time Stamp Request + +To create a time stamp request for design1.txt with SHA-1 +without nonce and policy and no certificate is required in the response: + + openssl ts -query -data design1.txt -no_nonce \ + -out design1.tsq + +To create a similar time stamp request with specifying the message imprint +explicitly: + + openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -no_nonce -out design1.tsq + +To print the content of the previous request in human readable format: + + openssl ts -query -in design1.tsq -text + +To create a time stamp request which includes the MD-5 digest +of design2.txt, requests the signer certificate and nonce, +specifies a policy id (assuming the tsa_policy1 name is defined in the +OID section of the config file): + + openssl ts -query -data design2.txt -md5 \ + -policy tsa_policy1 -cert -out design2.tsq + +=head2 Time Stamp Response + +Before generating a response a signing certificate must be created for +the TSA that contains the B<timeStamping> critical extended key usage extension +without any other key usage extensions. You can add the +'extendedKeyUsage = critical,timeStamping' line to the user certificate section +of the config file to generate a proper certificate. See L<req(1)|req(1)>, +L<ca(1)|ca(1)>, L<x509(1)|x509(1)> for instructions. The examples +below assume that cacert.pem contains the certificate of the CA, +tsacert.pem is the signing certificate issued by cacert.pem and +tsakey.pem is the private key of the TSA. + +To create a time stamp response for a request: + + openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \ + -signer tsacert.pem -out design1.tsr + +If you want to use the settings in the config file you could just write: + + openssl ts -reply -queryfile design1.tsq -out design1.tsr + +To print a time stamp reply to stdout in human readable format: + + openssl ts -reply -in design1.tsr -text + +To create a time stamp token instead of time stamp response: + + openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out + +To print a time stamp token to stdout in human readable format: + + openssl ts -reply -in design1_token.der -token_in -text -token_out + +To extract the time stamp token from a response: + + openssl ts -reply -in design1.tsr -out design1_token.der -token_out + +To add 'granted' status info to a time stamp token thereby creating a +valid response: + + openssl ts -reply -in design1_token.der -token_in -out design1.tsr + +=head2 Time Stamp Verification + +To verify a time stamp reply against a request: + + openssl ts -verify -queryfile design1.tsq -in design1.tsr \ + -CAfile cacert.pem -untrusted tsacert.pem + +To verify a time stamp reply that includes the certificate chain: + + openssl ts -verify -queryfile design2.tsq -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against the original data file: + openssl ts -verify -data design2.txt -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against a message imprint: + openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -in design2.tsr -CAfile cacert.pem + +You could also look at the 'test' directory for more examples. + +=head1 BUGS + +If you find any bugs or you have suggestions please write to +Zoltan Glozik <zglozik@opentsa.org>. Known issues: + +=over 4 + +=item * No support for time stamps over SMTP, though it is quite easy +to implement an automatic e-mail based TSA with L<procmail(1)|procmail(1)> +and L<perl(1)|perl(1)>. HTTP server support is provided in the form of +a separate apache module. HTTP client support is provided by +L<tsget(1)|tsget(1)>. Pure TCP/IP protocol is not supported. + +=item * The file containing the last serial number of the TSA is not +locked when being read or written. This is a problem if more than one +instance of L<openssl(1)|openssl(1)> is trying to create a time stamp +response at the same time. This is not an issue when using the apache +server module, it does proper locking. + +=item * Look for the FIXME word in the source files. + +=item * The source code should really be reviewed by somebody else, too. + +=item * More testing is needed, I have done only some basic tests (see +test/testtsa). + +=back + +=cut + +=head1 AUTHOR + +Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) + +=head1 SEE ALSO + +L<tsget(1)|tsget(1)>, L<openssl(1)|openssl(1)>, L<req(1)|req(1)>, +L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, +L<config(5)|config(5)> + +=cut diff --git a/openssl/doc/apps/tsget.pod b/openssl/doc/apps/tsget.pod new file mode 100644 index 000000000..b05957bee --- /dev/null +++ b/openssl/doc/apps/tsget.pod @@ -0,0 +1,194 @@ +=pod + +=head1 NAME + +tsget - Time Stamping HTTP/HTTPS client + +=head1 SYNOPSIS + +B<tsget> +B<-h> server_url +[B<-e> extension] +[B<-o> output] +[B<-v>] +[B<-d>] +[B<-k> private_key.pem] +[B<-p> key_password] +[B<-c> client_cert.pem] +[B<-C> CA_certs.pem] +[B<-P> CA_path] +[B<-r> file:file...] +[B<-g> EGD_socket] +[request]... + +=head1 DESCRIPTION + +The B<tsget> command can be used for sending a time stamp request, as +specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing +the time stamp response in a file. This tool cannot be used for creating the +requests and verifying responses, you can use the OpenSSL B<ts(1)> command to +do that. B<tsget> can send several requests to the server without closing +the TCP connection if more than one requests are specified on the command +line. + +The tool sends the following HTTP request for each time stamp request: + + POST url HTTP/1.1 + User-Agent: OpenTSA tsget.pl/<version> + Host: <host>:<port> + Pragma: no-cache + Content-Type: application/timestamp-query + Accept: application/timestamp-reply + Content-Length: length of body + + ...binary request specified by the user... + +B<tsget> expects a response of type application/timestamp-reply, which is +written to a file without any interpretation. + +=head1 OPTIONS + +=over 4 + +=item B<-h> server_url + +The URL of the HTTP/HTTPS server listening for time stamp requests. + +=item B<-e> extension + +If the B<-o> option is not given this argument specifies the extension of the +output files. The base name of the output file will be the same as those of +the input files. Default extension is '.tsr'. (Optional) + +=item B<-o> output + +This option can be specified only when just one request is sent to the +server. The time stamp response will be written to the given output file. '-' +means standard output. In case of multiple time stamp requests or the absence +of this argument the names of the output files will be derived from the names +of the input files and the default or specified extension argument. (Optional) + +=item B<-v> + +The name of the currently processed request is printed on standard +error. (Optional) + +=item B<-d> + +Switches on verbose mode for the underlying B<curl> library. You can see +detailed debug messages for the connection. (Optional) + +=item B<-k> private_key.pem + +(HTTPS) In case of certificate-based client authentication over HTTPS +<private_key.pem> must contain the private key of the user. The private key +file can optionally be protected by a passphrase. The B<-c> option must also +be specified. (Optional) + +=item B<-p> key_password + +(HTTPS) Specifies the passphrase for the private key specified by the B<-k> +argument. If this option is omitted and the key is passphrase protected B<tsget> +will ask for it. (Optional) + +=item B<-c> client_cert.pem + +(HTTPS) In case of certificate-based client authentication over HTTPS +<client_cert.pem> must contain the X.509 certificate of the user. The B<-k> +option must also be specified. If this option is not specified no +certificate-based client authentication will take place. (Optional) + +=item B<-C> CA_certs.pem + +(HTTPS) The trusted CA certificate store. The certificate chain of the peer's +certificate must include one of the CA certificates specified in this file. +Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional) + +=item B<-P> CA_path + +(HTTPS) The path containing the trusted CA certificates to verify the peer's +certificate. The directory must be prepared with the B<c_rehash> +OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of +HTTPS. (Optional) + +=item B<-rand> file:file... + +The files containing random data for seeding the random number +generator. Multiple files can be specified, the separator is B<;> for +MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) + +=item B<-g> EGD_socket + +The name of an EGD socket to get random data from. (Optional) + +=item [request]... + +List of files containing B<RFC 3161> DER-encoded time stamp requests. If no +requests are specifed only one request will be sent to the server and it will be +read from the standard input. (Optional) + +=back + +=head1 ENVIRONMENT VARIABLES + +The B<TSGET> environment variable can optionally contain default +arguments. The content of this variable is added to the list of command line +arguments. + +=head1 EXAMPLES + +The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid +time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests +and at port 8443 for HTTPS requests, the TSA service is available at the /tsa +absolute path. + +Get a time stamp response for file1.tsq over HTTP, output is written to +file1.tsr: + + tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq + +Get a time stamp response for file1.tsq and file2.tsq over HTTP showing +progress, output is written to file1.reply and file2.reply respectively: + + tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ + file1.tsq file2.tsq + +Create a time stamp request, write it to file3.tsq, send it to the server and +write the response to file3.tsr: + + openssl ts -query -data file3.txt -cert | tee file3.tsq \ + | tsget -h http://tsa.opentsa.org:8080/tsa \ + -o file3.tsr + +Get a time stamp response for file1.tsq over HTTPS without client +authentication: + + tsget -h https://tsa.opentsa.org:8443/tsa \ + -C cacerts.pem file1.tsq + +Get a time stamp response for file1.tsq over HTTPS with certificate-based +client authentication (it will ask for the passphrase if client_key.pem is +protected): + + tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ + -k client_key.pem -c client_cert.pem file1.tsq + +You can shorten the previous command line if you make use of the B<TSGET> +environment variable. The following commands do the same as the previous +example: + + TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ + -k client_key.pem -c client_cert.pem' + export TSGET + tsget file1.tsq + +=head1 AUTHOR + +Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) + +=head1 SEE ALSO + +L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>, +B<RFC 3161> + +=cut diff --git a/openssl/doc/apps/verify.pod b/openssl/doc/apps/verify.pod index ff2629d2c..336098f1e 100644 --- a/openssl/doc/apps/verify.pod +++ b/openssl/doc/apps/verify.pod @@ -10,6 +10,18 @@ B<openssl> B<verify> [B<-CApath directory>] [B<-CAfile file>] [B<-purpose purpose>] +[B<-policy arg>] +[B<-ignore_critical>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-policy_check>] +[B<-explicit_policy>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-x509_strict>] +[B<-extended_crl>] +[B<-use_deltas>] +[B<-policy_print>] [B<-untrusted file>] [B<-help>] [B<-issuer_checks>] @@ -66,6 +78,68 @@ certificate was rejected. However the presence of rejection messages does not itself imply that anything is wrong: during the normal verify process several rejections may take place. +=item B<-policy arg> + +Enable policy processing and add B<arg> to the user-initial-policy-set +(see RFC3280 et al). The policy B<arg> can be an object name an OID in numeric +form. This argument can appear more than once. + +=item B<-policy_check> + +Enables certificate policy processing. + +=item B<-explicit_policy> + +Set policy variable require-explicit-policy (see RFC3280 et al). + +=item B<-inhibit_any> + +Set policy variable inhibit-any-policy (see RFC3280 et al). + +=item B<-inhibit_map> + +Set policy variable inhibit-policy-mapping (see RFC3280 et al). + +=item B<-policy_print> + +Print out diagnostics, related to policy checking + +=item B<-crl_check> + +Checks end entity certificate validity by attempting to lookup a valid CRL. +If a valid CRL cannot be found an error occurs. + +=item B<-crl_check_all> + +Checks the validity of B<all> certificates in the chain by attempting +to lookup valid CRLs. + +=item B<-ignore_critical> + +Normally if an unhandled critical extension is present which is not +supported by OpenSSL the certificate is rejected (as required by +RFC3280 et al). If this option is set critical extensions are +ignored. + +=item B<-x509_strict> + +Disable workarounds for broken certificates which have to be disabled +for strict X.509 compliance. + +=item B<-extended_crl> + +Enable extended CRL features such as indirect CRLs and alternate CRL +signing keys. + +=item B<-use_deltas> + +Enable support for delta CRLs. + +=item B<-check_ss_sig> + +Verify the signature on the self-signed root CA. This is disabled by default +because it doesn't add any security. + =item B<-> marks the last option. All arguments following this are assumed to be @@ -166,12 +240,12 @@ the operation was successful. =item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> -the issuer certificate could not be found: this occurs if the issuer certificate -of an untrusted certificate cannot be found. +the issuer certificate of a looked up certificate could not be found. This +normally means the list of trusted certificates is not complete. =item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> -the CRL of a certificate could not be found. Unused. +the CRL of a certificate could not be found. =item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> @@ -194,7 +268,7 @@ the signature of the certificate is invalid. =item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> -the signature of the certificate is invalid. Unused. +the signature of the certificate is invalid. =item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> @@ -206,11 +280,11 @@ the certificate has expired: that is the notAfter date is before the current tim =item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> -the CRL is not yet valid. Unused. +the CRL is not yet valid. =item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> -the CRL has expired. Unused. +the CRL has expired. =item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> @@ -222,11 +296,11 @@ the certificate notAfter field contains an invalid time. =item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> -the CRL lastUpdate field contains an invalid time. Unused. +the CRL lastUpdate field contains an invalid time. =item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> -the CRL nextUpdate field contains an invalid time. Unused. +the CRL nextUpdate field contains an invalid time. =item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> @@ -244,8 +318,8 @@ be found locally. =item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> -the issuer certificate of a locally looked up certificate could not be found. This normally means -the list of trusted certificates is not complete. +the issuer certificate could not be found: this occurs if the issuer +certificate of an untrusted certificate cannot be found. =item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> @@ -258,7 +332,7 @@ the certificate chain length is greater than the supplied maximum depth. Unused. =item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> -the certificate has been revoked. Unused. +the certificate has been revoked. =item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> @@ -321,6 +395,10 @@ the certificates in the file will be recognised. Previous versions of OpenSSL assume certificates with matching subject name are identical and mishandled them. +Previous versions of this documentation swapped the meaning of the +B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and +B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. + =head1 SEE ALSO L<x509(1)|x509(1)> diff --git a/openssl/doc/apps/x509.pod b/openssl/doc/apps/x509.pod index f43c17523..3002b0812 100644 --- a/openssl/doc/apps/x509.pod +++ b/openssl/doc/apps/x509.pod @@ -23,6 +23,7 @@ B<openssl> B<x509> [B<-issuer>] [B<-nameopt option>] [B<-email>] +[B<-ocsp_uri>] [B<-startdate>] [B<-enddate>] [B<-purpose>] @@ -103,7 +104,7 @@ then this option has no effect: SHA1 is always used with DSA keys. =item B<-engine id> -specifying an engine (by it's unique B<id> string) will cause B<req> +specifying an engine (by its unique B<id> string) will cause B<x509> 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. @@ -157,6 +158,16 @@ outputs the "hash" of the certificate issuer name. synonym for "-subject_hash" for backward compatibility reasons. +=item B<-subject_hash_old> + +outputs the "hash" of the certificate subject name using the older algorithm +as used by OpenSSL versions before 1.0.0. + +=item B<-issuer_hash_old> + +outputs the "hash" of the certificate issuer name using the older algorithm +as used by OpenSSL versions before 1.0.0. + =item B<-subject> outputs the subject name. @@ -176,6 +187,10 @@ set multiple options. See the B<NAME OPTIONS> section for more information. outputs the email address(es) if any. +=item B<-ocsp_uri> + +outputs the OCSP responder address(es) if any. + =item B<-startdate> prints out the start date of the certificate, that is the notBefore date. @@ -376,7 +391,9 @@ no extensions are added to the certificate. the section to add certificate extensions from. If this option is not specified then the extensions should either be contained in the unnamed (default) section or the default section should contain a variable called -"extensions" which contains the section to use. +"extensions" which contains the section to use. See the +L<x509v3_config(5)|x509v3_config(5)> manual page for details of the +extension section format. =back @@ -823,10 +840,17 @@ OpenSSL 0.9.5 and later. =head1 SEE ALSO L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)> +L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>, +L<x509v3_config(5)|x509v3_config(5)> =head1 HISTORY Before OpenSSL 0.9.8, the default digest for RSA keys was MD5. +The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options +before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding +of the distinguished name. In OpenSSL 1.0.0 and later it is based on a +canonical version of the DN using SHA1. This means that any directories using +the old form must have their links rebuilt using B<c_rehash> or similar. + =cut diff --git a/openssl/doc/apps/x509v3_config.pod b/openssl/doc/apps/x509v3_config.pod index 38c46e85c..0450067cf 100644 --- a/openssl/doc/apps/x509v3_config.pod +++ b/openssl/doc/apps/x509v3_config.pod @@ -52,7 +52,7 @@ use is defined by the extension code itself: check out the certificate policies extension for an example. If an extension type is unsupported then the I<arbitrary> extension syntax -must be used, see the L<ARBITRART EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details. +must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details. =head1 STANDARD EXTENSIONS @@ -178,7 +178,7 @@ preceeding the name with a B<+> character. otherName can include arbitrary data associated with an OID: the value should be the OID followed by a semicolon and the content in standard -ASN1_generate_nconf() format. +L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. Examples: @@ -226,21 +226,82 @@ Example: =head2 CRL distribution points. -This is a multi-valued extension that supports all the literal options of -subject alternative name. Of the few software packages that currently interpret -this extension most only interpret the URI option. +This is a multi-valued extension whose options can be either in name:value pair +using the same form as subject alternative name or a single value representing +a section name containing all the distribution point fields. -Currently each option will set a new DistributionPoint with the fullName -field set to the given value. +For a name:value pair a new DistributionPoint with the fullName field set to +the given value both the cRLissuer and reasons fields are omitted in this case. -Other fields like cRLissuer and reasons cannot currently be set or displayed: -at this time no examples were available that used these fields. +In the single option case the section indicated contains values for each +field. In this section: -Examples: +If the name is "fullname" the value field should contain the full name +of the distribution point in the same format as subject alternative name. + +If the name is "relativename" then the value field should contain a section +name whose contents represent a DN fragment to be placed in this field. + +The name "CRLIssuer" if present should contain a value for this field in +subject alternative name format. + +If the name is "reasons" the value field should consist of a comma +separated field containing the reasons. Valid reasons are: "keyCompromise", +"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation", +"certificateHold", "privilegeWithdrawn" and "AACompromise". + + +Simple examples: crlDistributionPoints=URI:http://myhost.com/myca.crl crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl +Full distribution point example: + + crlDistributionPoints=crldp1_section + + [crldp1_section] + + fullname=URI:http://myhost.com/myca.crl + CRLissuer=dirName:issuer_sect + reasons=keyCompromise, CACompromise + + [issuer_sect] + C=UK + O=Organisation + CN=Some Name + +=head2 Issuing Distribution Point + +This extension should only appear in CRLs. It is a multi valued extension +whose syntax is similar to the "section" pointed to by the CRL distribution +points extension with a few differences. + +The names "reasons" and "CRLissuer" are not recognized. + +The name "onlysomereasons" is accepted which sets this field. The value is +in the same format as the CRL distribution point "reasons" field. + +The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted +the values should be a boolean value (TRUE or FALSE) to indicate the value of +the corresponding field. + +Example: + + issuingDistributionPoint=critical, @idp_section + + [idp_section] + + fullname=URI:http://myhost.com/myca.crl + indirectCRL=TRUE + onlysomereasons=keyCompromise, CACompromise + + [issuer_sect] + C=UK + O=Organisation + CN=Some Name + + =head2 Certificate Policies. This is a I<raw> extension. All the fields of this extension can be set by @@ -329,6 +390,16 @@ Examples: nameConstraints=permitted;email:.somedomain.com nameConstraints=excluded;email:.com +issuingDistributionPoint = idp_section + +=head2 OCSP No Check + +The OCSP No Check extension is a string extension but its value is ignored. + +Example: + + noCheck = ignored + =head1 DEPRECATED EXTENSIONS @@ -370,7 +441,8 @@ the data is formatted correctly for the given extension type. There are two ways to encode arbitrary extensions. The first way is to use the word ASN1 followed by the extension content -using the same syntax as ASN1_generate_nconf(). For example: +using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>. +For example: 1.2.3.4=critical,ASN1:UTF8String:Some random data @@ -450,7 +522,8 @@ for arbitrary extensions was added in OpenSSL 0.9.8 =head1 SEE ALSO -L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)> +L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>, +L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> =cut diff --git a/openssl/doc/crypto/ASN1_OBJECT_new.pod b/openssl/doc/crypto/ASN1_OBJECT_new.pod index 51679bfcd..9bae40fcc 100644 --- a/openssl/doc/crypto/ASN1_OBJECT_new.pod +++ b/openssl/doc/crypto/ASN1_OBJECT_new.pod @@ -6,6 +6,8 @@ ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions =head1 SYNOPSIS + #include <openssl/asn1.h> + ASN1_OBJECT *ASN1_OBJECT_new(void); void ASN1_OBJECT_free(ASN1_OBJECT *a); diff --git a/openssl/doc/crypto/ASN1_STRING_length.pod b/openssl/doc/crypto/ASN1_STRING_length.pod index c4ec693f1..a08e9a0fa 100644 --- a/openssl/doc/crypto/ASN1_STRING_length.pod +++ b/openssl/doc/crypto/ASN1_STRING_length.pod @@ -8,6 +8,8 @@ ASN1_STRING utility functions =head1 SYNOPSIS + #include <openssl/asn1.h> + int ASN1_STRING_length(ASN1_STRING *x); unsigned char * ASN1_STRING_data(ASN1_STRING *x); diff --git a/openssl/doc/crypto/ASN1_STRING_new.pod b/openssl/doc/crypto/ASN1_STRING_new.pod index 5b1bbb7eb..8ac2a03ae 100644 --- a/openssl/doc/crypto/ASN1_STRING_new.pod +++ b/openssl/doc/crypto/ASN1_STRING_new.pod @@ -7,6 +7,8 @@ ASN1_STRING allocation functions =head1 SYNOPSIS + #include <openssl/asn1.h> + ASN1_STRING * ASN1_STRING_new(void); ASN1_STRING * ASN1_STRING_type_new(int type); void ASN1_STRING_free(ASN1_STRING *a); diff --git a/openssl/doc/crypto/ASN1_generate_nconf.pod b/openssl/doc/crypto/ASN1_generate_nconf.pod index 1157cff51..542fd1579 100644 --- a/openssl/doc/crypto/ASN1_generate_nconf.pod +++ b/openssl/doc/crypto/ASN1_generate_nconf.pod @@ -6,6 +6,8 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions =head1 SYNOPSIS + #include <openssl/asn1.h> + ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf); @@ -101,7 +103,8 @@ bits is set to zero. =item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>, B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>, B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>, -B<T61STRING>, B<TELETEXSTRING>, B<GeneralString> +B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>, +B<NUMERIC> These encode the corresponding string types. B<value> represents the contents of this structure. The format can be B<ASCII> or B<UTF8>. @@ -175,7 +178,7 @@ An IA5String explicitly tagged using APPLICATION tagging: A BITSTRING with bits 1 and 5 set and all others zero: - FORMAT=BITLIST,BITSTRING:1,5 + FORMAT:BITLIST,BITSTRING:1,5 A more complex example using a config file to produce a SEQUENCE consiting of a BOOL an OID and a UTF8String: diff --git a/openssl/doc/crypto/BIO_f_md.pod b/openssl/doc/crypto/BIO_f_md.pod index 0d24083e6..2cc41f89d 100644 --- a/openssl/doc/crypto/BIO_f_md.pod +++ b/openssl/doc/crypto/BIO_f_md.pod @@ -58,6 +58,12 @@ If an application needs to call BIO_gets() or BIO_puts() through a chain containing digest BIOs then this can be done by prepending a buffering BIO. +Before OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO +had been initialized for example by calling BIO_set_md() ). In OpenSSL +1.0.0 and later the context is always returned and the BIO is state is set +to initialized. This allows applications to initialize the context externally +if the standard calls such as BIO_set_md() are not sufficiently flexible. + =head1 RETURN VALUES BIO_f_md() returns the digest BIO method. diff --git a/openssl/doc/crypto/BIO_f_ssl.pod b/openssl/doc/crypto/BIO_f_ssl.pod index f0b731731..bc5861ab3 100644 --- a/openssl/doc/crypto/BIO_f_ssl.pod +++ b/openssl/doc/crypto/BIO_f_ssl.pod @@ -308,6 +308,15 @@ a client and also echoes the request to standard output. BIO_free_all(sbio); +=head1 BUGS + +In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, +the I/O BIO reference count was incorrectly incremented (instead of +decremented) and dissociated with the SSL BIO even if the SSL BIO was not +explicitly being popped (e.g. a pop higher up the chain). Applications which +included workarounds for this bug (e.g. freeing BIOs more than once) should +be modified to handle this fix or they may free up an already freed BIO. + =head1 SEE ALSO TBA diff --git a/openssl/doc/crypto/BIO_new_CMS.pod b/openssl/doc/crypto/BIO_new_CMS.pod new file mode 100644 index 000000000..9e3a4b7f8 --- /dev/null +++ b/openssl/doc/crypto/BIO_new_CMS.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + + BIO_new_CMS - CMS streaming filter BIO + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output +of the filter is written to B<out>. Any data written to the chain is +automatically translated to a BER format CMS structure of the appropriate type. + +=head1 NOTES + +The chain returned by this function behaves like a standard filter BIO. It +supports non blocking I/O. Content is processed and streamed on the fly and not +all held in memory at once: so it is possible to encode very large structures. +After all content has been written through the chain BIO_flush() must be called +to finalise the structure. + +The B<CMS_STREAM> flag must be included in the corresponding B<flags> +parameter of the B<cms> creation function. + +If an application wishes to write additional data to B<out> BIOs should be +removed from the chain using BIO_pop() and freed with BIO_free() until B<out> +is reached. If no additional data needs to be written BIO_free_all() can be +called to free up the whole chain. + +Any content written through the filter is used verbatim: no canonical +translation is performed. + +It is possible to chain multiple BIOs to, for example, create a triple wrapped +signed, enveloped, signed structure. In this case it is the applications +responsibility to set the inner content type of any outer CMS_ContentInfo +structures. + +Large numbers of small writes through the chain should be avoided as this will +produce an output consisting of lots of OCTET STRING structures. Prepending +a BIO_f_buffer() buffering BIO will prevent this. + +=head1 BUGS + +There is currently no corresponding inverse BIO: i.e. one which can decode +a CMS structure on the fly. + +=head1 RETURN VALUES + +BIO_new_CMS() returns a BIO chain when successful or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_encrypt(3)|CMS_encrypt(3)> + +=head1 HISTORY + +BIO_new_CMS() was added to OpenSSL 1.0.0 + +=cut diff --git a/openssl/doc/crypto/BIO_s_mem.pod b/openssl/doc/crypto/BIO_s_mem.pod index 19648acfa..8f85e0dce 100644 --- a/openssl/doc/crypto/BIO_s_mem.pod +++ b/openssl/doc/crypto/BIO_s_mem.pod @@ -74,7 +74,7 @@ Writes to memory BIOs will always succeed if memory is available: that is their size can grow indefinitely. Every read from a read write memory BIO will remove the data just read with -an internal copy operation, if a BIO contains a lots of data and it is +an internal copy operation, if a BIO contains a lot of data and it is read in small chunks the operation can be very slow. The use of a read only memory BIO avoids this problem. If the BIO must be read write then adding a buffering BIO to the chain will speed up the process. diff --git a/openssl/doc/crypto/BN_BLINDING_new.pod b/openssl/doc/crypto/BN_BLINDING_new.pod index 7b087f728..5f51fdb47 100644 --- a/openssl/doc/crypto/BN_BLINDING_new.pod +++ b/openssl/doc/crypto/BN_BLINDING_new.pod @@ -22,8 +22,11 @@ functions. BN_CTX *ctx); int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b, BN_CTX *ctx); + #ifndef OPENSSL_NO_DEPRECATED unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); + #endif + CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *); unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, @@ -54,11 +57,11 @@ BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() with B<r> set to NULL. -BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id() -set and get the "thread id" value of the B<BN_BLINDING> structure, -a field provided to users of B<BN_BLINDING> structure to help them -provide proper locking if needed for multi-threaded use. The -"thread id" of a newly allocated B<BN_BLINDING> structure is zero. +BN_BLINDING_thread_id() provides access to the B<CRYPTO_THREADID> +object within the B<BN_BLINDING> structure. This is to help users +provide proper locking if needed for multi-threaded use. The "thread +id" object of a newly allocated B<BN_BLINDING> structure is +initialised to the thread id in which BN_BLINDING_new() was called. BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently there are two supported flags: B<BN_BLINDING_NO_UPDATE> and @@ -83,8 +86,8 @@ BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(), BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on success and 0 if an error occured. -BN_BLINDING_get_thread_id() returns the thread id (a B<unsigned long> -value) or 0 if not set. +BN_BLINDING_thread_id() returns a pointer to the thread id object +within a B<BN_BLINDING> object. BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags (a B<unsigned long> value). @@ -98,6 +101,9 @@ L<bn(3)|bn(3)> =head1 HISTORY +BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it +deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id. + BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8 diff --git a/openssl/doc/crypto/CMS_add0_cert.pod b/openssl/doc/crypto/CMS_add0_cert.pod new file mode 100644 index 000000000..9c13f488f --- /dev/null +++ b/openssl/doc/crypto/CMS_add0_cert.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + + CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_get1_crls, - CMS certificate and CRL utility functions + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert); + int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert); + STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms); + + int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl); + int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl); + STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms); + + +=head1 DESCRIPTION + +CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>. +must be of type signed data or enveloped data. + +CMS_get1_certs() returns all certificates in B<cms>. + +CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls() +returns any CRLs in B<cms>. + +=head1 NOTES + +The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped +data or an error will be returned. + +For signed data certificates and CRLs are added to the B<certificates> and +B<crls> fields of SignedData structure. For enveloped data they are added to +B<OriginatorInfo>. + +As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it +must not be freed up after the call as opposed to CMS_add1_cert() where B<cert> +must be freed up. + +The same certificate or CRL must not be added to the same cms structure more +than once. + +=head1 RETURN VALUES + +CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return +1 for success and 0 for failure. + +CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs +or NULL if there are none or an error occurs. The only error which will occur +in practice is if the B<cms> type is invalid. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, +L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_encrypt(3)|CMS_encrypt(3)> + +=head1 HISTORY + +CMS_add0_cert(), CMS_add1_cert(), CMS_get1_certs(), CMS_add0_crl() +and CMS_get1_crls() were all first added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_add1_recipient_cert.pod b/openssl/doc/crypto/CMS_add1_recipient_cert.pod new file mode 100644 index 000000000..d7d8e2532 --- /dev/null +++ b/openssl/doc/crypto/CMS_add1_recipient_cert.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + + CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags); + + CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType); + +=head1 DESCRIPTION + +CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped +data structure B<cms> as a KeyTransRecipientInfo structure. + +CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using +wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional +values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped +data structure B<cms> as a KEKRecipientInfo structure. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_encrypt() with the flag B<CMS_PARTIAL> set. + +=head1 NOTES + +The main purpose of this function is to provide finer control over a CMS +enveloped data structure where the simpler CMS_encrypt() function defaults are +not appropriate. For example if one or more KEKRecipientInfo structures +need to be added. New attributes can also be added using the returned +CMS_RecipientInfo structure and the CMS attribute utility functions. + +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. + +Currently only AES based key wrapping algorithms are supported for B<nid>, +specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. +If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used +consistent with B<keylen>. + +=head1 RETURN VALUES + +CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal +pointer to the CMS_RecipientInfo structure just added or NULL if an error +occurs. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>, +L<CMS_final(3)|CMS_final(3)>, + +=head1 HISTORY + +CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL +0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_compress.pod b/openssl/doc/crypto/CMS_compress.pod new file mode 100644 index 000000000..0a0715271 --- /dev/null +++ b/openssl/doc/crypto/CMS_compress.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +CMS_compress - create a CMS CompressedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags); + +=head1 DESCRIPTION + +CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid> +is the compression algorithm to use or B<NID_undef> to use the default +algorithm (zlib compression). B<in> is the content to be compressed. +B<flags> is an optional set of flags. + +=head1 NOTES + +The only currently supported compression algorithm is zlib using the NID +NID_zlib_compression. + +If zlib support is not compiled into OpenSSL then CMS_compress() will return +an error. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are +prepended to the data. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<CMS_BINARY> 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<CMS_BINARY> is set then +B<CMS_TEXT> is ignored. + +If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is +returned suitable for streaming I/O: no data is read from the BIO B<in>. + +The compressed data is included in the CMS_ContentInfo structure, unless +B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in +practice and is not supported by SMIME_write_CMS(). + +=head1 NOTES + +If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is +B<not> complete and outputting its contents via a function that does not +properly finalize the B<CMS_ContentInfo> structure will give unpredictable +results. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_CMS(). + +Additional compression parameters such as the zlib compression level cannot +currently be set. + +=head1 RETURN VALUES + +CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_uncompress(3)|CMS_uncompress(3)> + +=head1 HISTORY + +CMS_compress() was added to OpenSSL 0.9.8 +The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. + +=cut diff --git a/openssl/doc/crypto/CMS_decrypt.pod b/openssl/doc/crypto/CMS_decrypt.pod new file mode 100644 index 000000000..d857e4f93 --- /dev/null +++ b/openssl/doc/crypto/CMS_decrypt.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + + CMS_decrypt - decrypt content from a CMS envelopedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags); + +=head1 DESCRIPTION + +CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData +structure. B<pkey> is the private key of the recipient, B<cert> is the +recipient's certificate, B<out> is a BIO to write the content to and +B<flags> is an optional set of flags. + +The B<dcont> parameter is used in the rare case where the encrypted content +is detached. It will normally be set to NULL. + +=head1 NOTES + +OpenSSL_add_all_algorithms() (or equivalent) should be called before using this +function or errors about unknown algorithms will occur. + +Although the recipients certificate is not needed to decrypt the data it is +needed to locate the appropriate (of possible several) recipients in the CMS +structure. If B<cert> is set to NULL all possible recipients are tried. + +It is possible to determine the correct recipient key by other means (for +example looking them up in a database) and setting them in the CMS structure +in advance using the CMS utility functions such as CMS_set1_pkey(). In this +case both B<cert> and B<pkey> should be set to NULL. + +To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() +and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and +B<cert> and B<pkey> set to NULL. + +The following flags can be passed in the B<flags> parameter. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +=head1 RETURN VALUES + +CMS_decrypt() returns either 1 for success or 0 for failure. +The error can be obtained from ERR_get_error(3) + +=head1 BUGS + +The lack of single pass processing and the need to hold all data in memory as +mentioned in CMS_verify() also applies to CMS_decrypt(). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> + +=head1 HISTORY + +CMS_decrypt() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_encrypt.pod b/openssl/doc/crypto/CMS_encrypt.pod new file mode 100644 index 000000000..1ee5b275e --- /dev/null +++ b/openssl/doc/crypto/CMS_encrypt.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + + CMS_encrypt - create a CMS envelopedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags); + +=head1 DESCRIPTION + +CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs> +is a list of recipient certificates. B<in> is the content to be encrypted. +B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. + +=head1 NOTES + +Only certificates carrying RSA keys are supported so the recipient certificates +supplied to this function must all contain RSA public keys, though they do not +have to be signed using the RSA algorithm. + +EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use +because most clients will support it. + +The algorithm passed in the B<cipher> parameter must support ASN1 encoding of +its parameters. + +Many browsers implement a "sign and encrypt" option which is simply an S/MIME +envelopedData containing an S/MIME signed message. This can be readily produced +by storing the S/MIME signed message in a memory BIO and passing it to +CMS_encrypt(). + +The following flags can be passed in the B<flags> parameter. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are +prepended to the data. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<CMS_BINARY> 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<CMS_BINARY> is set then +B<CMS_TEXT> is ignored. + +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. + +If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is +returned suitable for streaming I/O: no data is read from the BIO B<in>. + +If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is +returned to which additional recipients and attributes can be added before +finalization. + +The data being encrypted is included in the CMS_ContentInfo structure, unless +B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in +practice and is not supported by SMIME_write_CMS(). + +=head1 NOTES + +If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is +B<not> complete and outputting its contents via a function that does not +properly finalize the B<CMS_ContentInfo> structure will give unpredictable +results. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_CMS(). + +The recipients specified in B<certs> use a CMS KeyTransRecipientInfo info +structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL> +and CMS_add0_recipient_key(). + +The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients +added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key(). + +=head1 RETURN VALUES + +CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> + +=head1 HISTORY + +CMS_decrypt() was added to OpenSSL 0.9.8 +The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. + +=cut diff --git a/openssl/doc/crypto/CMS_final.pod b/openssl/doc/crypto/CMS_final.pod new file mode 100644 index 000000000..36cf96b8a --- /dev/null +++ b/openssl/doc/crypto/CMS_final.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + + CMS_final - finalise a CMS_ContentInfo structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); + +=head1 DESCRIPTION + +CMS_final() finalises the structure B<cms>. It's purpose is to perform any +operations necessary on B<cms> (digest computation for example) and set the +appropriate fields. The parameter B<data> contains the content to be +processed. The B<dcont> parameter contains a BIO to write content to after +processing: this is only used with detached data and will usually be set to +NULL. + +=head1 NOTES + +This function will normally be called when the B<CMS_PARTIAL> flag is used. It +should only be used when streaming is not performed because the streaming +I/O functions perform finalisation operations internally. + +=head1 RETURN VALUES + +CMS_final() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_encrypt(3)|CMS_encrypt(3)> + +=head1 HISTORY + +CMS_final() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get0_RecipientInfos.pod b/openssl/doc/crypto/CMS_get0_RecipientInfos.pod new file mode 100644 index 000000000..e0355423e --- /dev/null +++ b/openssl/doc/crypto/CMS_get0_RecipientInfos.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + + CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms); + int CMS_RecipientInfo_type(CMS_RecipientInfo *ri); + + int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); + int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert); + int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey); + + int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype); + int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen); + int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen); + + int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); + +=head1 DESCRIPTION + +The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo +structures associated with a CMS EnvelopedData structure. + +CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>. +It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, +CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. + +CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient +identifier associated with a specific CMS_RecipientInfo structure B<ri>, which +must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in +B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. + +CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the +CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS. +It returns zero if the comparison is successful and non zero if not. + +CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with +the CMS_RecipientInfo structure B<ri>, which must be of type +CMS_RECIPINFO_TRANS. + +CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the +CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any +of the remaining parameters can be NULL if the application is not interested in +the value of a field. Where a field is optional and absent NULL will be written +to the corresponding parameter. The keyEncryptionAlgorithm field is written to +B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if +present is written to B<pdate>, if the B<other> field is present the components +B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and +B<pothertype>. + +CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen> +parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>, +which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is +successful and non zero if not. + +CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length +B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type +CMS_RECIPINFO_KEK. + +CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure +B<ri> in structure B<cms>. A key must have been associated with the structure +first. + +=head1 NOTES + +The main purpose of these functions is to enable an application to lookup +recipient keys using any appropriate technique when the simpler method +of CMS_decrypt() is not appropriate. + +In typical usage and application will retrieve all CMS_RecipientInfo structures +using CMS_get0_RecipientInfos() and check the type of each using +CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure +can be ignored or its key identifier data retrieved using an appropriate +function. Then if the corresponding secret or private key can be obtained by +any appropriate means it can then associated with the structure and +CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called +with a NULL key to decrypt the enveloped content. + +=head1 RETURN VALUES + +CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if +an error occurs. + +CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), +CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and +CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. + +CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 +for a successful comparison and non zero otherwise. + +Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> + +=head1 HISTORY + +These functions were first was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get0_SignerInfos.pod b/openssl/doc/crypto/CMS_get0_SignerInfos.pod new file mode 100644 index 000000000..47f6d2a04 --- /dev/null +++ b/openssl/doc/crypto/CMS_get0_SignerInfos.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + + CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions. + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms); + + int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); + int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert); + void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer); + +=head1 DESCRIPTION + +The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures +associated with a CMS signedData structure. + +CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier +associated with a specific CMS_SignerInfo structure B<si>. Either the +keyidentifier will be set in B<keyid> or B<both> issuer name and serial number +in B<issuer> and B<sno>. + +CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer +identifier B<si>. It returns zero if the comparison is successful and non zero +if not. + +CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to +B<signer>. + +=head1 NOTES + +The main purpose of these functions is to enable an application to lookup +signers certificates using any appropriate technique when the simpler method +of CMS_verify() is not appropriate. + +In typical usage and application will retrieve all CMS_SignerInfo structures +using CMS_get0_SignerInfo() and retrieve the identifier information using +CMS. It will then obtain the signer certificate by some unspecified means +(or return and error if it cannot be found) and set it using +CMS_SignerInfo_set1_signer_cert(). + +Once all signer certificates have been set CMS_verify() can be used. + +Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if +there are no signers this is not a problem in practice because the only +error which can occur is if the B<cms> structure is not of type signedData +due to application error. + +=head1 RETURN VALUES + +CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there +are no signers or an error occurs. + +CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure. + +CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non +zero otherwise. + +CMS_SignerInfo_set1_signer_cert() does not return a value. + +Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> + +=head1 HISTORY + +These functions were first was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get0_type.pod b/openssl/doc/crypto/CMS_get0_type.pod new file mode 100644 index 000000000..8ff1c3115 --- /dev/null +++ b/openssl/doc/crypto/CMS_get0_type.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + + CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms); + int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid); + const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +CMS_get0_type() returns the content type of a CMS_ContentInfo structure as +and ASN1_OBJECT pointer. An application can then decide how to process the +CMS_ContentInfo structure based on this value. + +CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo +structure. It should be called with CMS functions with the B<CMS_PARTIAL> +flag and B<before> the structure is finalised, otherwise the results are +undefined. + +ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded +content type. + +=head1 NOTES + +As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal +pointers which should B<not> be freed up. CMS_set1_eContentType() copies the +supplied OID and it B<should> be freed up after use. + +The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value +using OBJ_obj2nid(). For the currently supported content types the following +values are returned: + + NID_pkcs7_data + NID_pkcs7_signed + NID_pkcs7_digest + NID_id_smime_ct_compressedData: + NID_pkcs7_encrypted + NID_pkcs7_enveloped + + +=head1 RETURN VALUES + +CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure. + +CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The +error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 HISTORY + +CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all +first added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod b/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod new file mode 100644 index 000000000..f546376a1 --- /dev/null +++ b/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + + CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions. + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); + int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); + int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); + void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto); + +=head1 DESCRIPTION + +CMS_ReceiptRequest_create0() creates a signed receipt request structure. The +B<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set +to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL +the allOrFirstTier option in B<receiptsFrom> is used and set to the value of +the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList> +option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the +B<receiptsTo> field value. + +The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr> +to SignerInfo structure B<si>. + +int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if +any is found it is decoded and written to B<prr>. + +CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. +The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier> +option of B<receiptsFrom> is used its value is copied to B<pallorfirst> +otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo> +parameter is copied to B<prto>. + +=head1 NOTES + +For more details of the meaning of the fields see RFC2634. + +The contents of a signed receipt should only be considered meaningful if the +corresponding CMS_ContentInfo structure can be successfully verified using +CMS_verify(). + +=head1 RETURN VALUES + +CMS_ReceiptRequest_create0() returns a signed receipt request structure or +NULL if an error occurred. + +CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred. + +CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and +decoded. It returns 0 if a signed receipt request is not present and -1 if +it is present but malformed. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, L<CMS_verify(3)|CMS_verify(3)> +L<CMS_verify_receipt(3)|CMS_verify_receipt(3)> + +=head1 HISTORY + +CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), +CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to +OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_sign.pod b/openssl/doc/crypto/CMS_sign.pod new file mode 100644 index 000000000..2cc72de32 --- /dev/null +++ b/openssl/doc/crypto/CMS_sign.pod @@ -0,0 +1,121 @@ +=pod + +=head1 NAME + + CMS_sign - create a CMS SignedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags); + +=head1 DESCRIPTION + +CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is +the certificate to sign with, B<pkey> is the corresponding private key. +B<certs> is an optional additional set of certificates to include in the CMS +structure (for example any intermediate CAs in the chain). Any or all of +these parameters can be B<NULL>, see B<NOTES> below. + +The data to be signed is read from BIO B<data>. + +B<flags> is an optional set of flags. + +=head1 NOTES + +Any of the following flags (ored together) can be passed in the B<flags> +parameter. + +Many S/MIME clients expect the signed content to include valid MIME headers. If +the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended +to the data. + +If B<CMS_NOCERTS> is set the signer's certificate will not be included in the +CMS_ContentInfo structure, the signer's certificate must still be supplied in +the B<signcert> parameter though. This can reduce the size of the signature if +the signers certificate can be obtained by other means: for example a +previously signed message. + +The data being signed is included in the CMS_ContentInfo structure, unless +B<CMS_DETACHED> is set in which case it is omitted. This is used for +CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed +messages for example. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<CMS_BINARY> is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. + +The SignedData structure includes several CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes +will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are +omitted. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. + +If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo> +structure is just initialized ready to perform the signing operation. The +signing is however B<not> performed and the data to be signed is not read from +the B<data> parameter. Signing is deferred until after the data has been +written. In this way data can be signed in a single pass. + +If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is +output to which additional signers and capabilities can be added before +finalization. + +If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is +B<not> complete and outputting its contents via a function that does not +properly finalize the B<CMS_ContentInfo> structure will give unpredictable +results. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_CMS(). + +If a signer is specified it will use the default digest for the signing +algorithm. This is B<SHA1> for both RSA and DSA keys. + +If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is +output. + +The function CMS_sign() is a basic CMS signing function whose output will be +suitable for many purposes. For finer control of the output format the +B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the +B<CMS_PARTIAL> flag set. Then one or more signers can be added using the +function CMS_sign_add1_signer(), non default digests can be used and custom +attributes added. B<CMS_final()> must then be called to finalize the +structure if streaming is not enabled. + +=head1 BUGS + +Some attributes such as counter signatures are not supported. + +=head1 RETURN VALUES + +CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> + +=head1 HISTORY + +CMS_sign() was added to OpenSSL 0.9.8 + +The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8, +it is supported for embedded data in OpenSSL 1.0.0 and later. + +=cut diff --git a/openssl/doc/crypto/CMS_sign_add1_signer.pod b/openssl/doc/crypto/CMS_sign_add1_signer.pod new file mode 100644 index 000000000..bda3ca2ad --- /dev/null +++ b/openssl/doc/crypto/CMS_sign_add1_signer.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + + CMS_sign_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); + + int CMS_SignerInfo_sign(CMS_SignerInfo *si); + + +=head1 DESCRIPTION + +CMS_sign_add1_signer() adds a signer with certificate B<signcert> and private +key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData +structure B<cms>. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a +valid CMS_ContentInfo SignedData structure. + +If the B<md> parameter is B<NULL> then the default digest for the public +key algorithm will be used. + +Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo +structure is not complete and must be finalized either by streaming (if +applicable) or a call to CMS_final(). + +The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo +structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags +are both set. + +=head1 NOTES + +The main purpose of CMS_sign_add1_signer() is to provide finer control +over a CMS signed data structure where the simpler CMS_sign() function defaults +are not appropriate. For example if multiple signers or non default digest +algorithms are needed. New attributes can also be added using the returned +CMS_SignerInfo structure and the CMS attribute utility functions or the +CMS signed receipt request functions. + +Any of the following flags (ored together) can be passed in the B<flags> +parameter. + +If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content +digest value from the CMS_ContentInfo structure: to add a signer to an existing +structure. An error occurs if a matching digest value cannot be found to copy. +The returned CMS_ContentInfo structure will be valid and finalized when this +flag is set. + +If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the +CMS_SignerInfo structure will not be finalized so additional attributes +can be added. In this case an explicit call to CMS_SignerInfo_sign() is +needed to finalize it. + +If B<CMS_NOCERTS> is set the signer's certificate will not be included in the +CMS_ContentInfo structure, the signer's certificate must still be supplied in +the B<signcert> parameter though. This can reduce the size of the signature if +the signers certificate can be obtained by other means: for example a +previously signed message. + +The SignedData structure includes several CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes +will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are +omitted. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. + +CMS_sign_add1_signer() returns an internal pointer to the CMS_SignerInfo +structure just added, this can be used to set additional attributes +before it is finalized. + +=head1 RETURN VALUES + +CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo +structure just added or NULL if an error occurs. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_final(3)|CMS_final(3)>, + +=head1 HISTORY + +CMS_sign_add1_signer() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_sign_receipt.pod b/openssl/doc/crypto/CMS_sign_receipt.pod new file mode 100644 index 000000000..cae1f8338 --- /dev/null +++ b/openssl/doc/crypto/CMS_sign_receipt.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + + CMS_sign_receipt - create a CMS signed receipt + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags); + +=head1 DESCRIPTION + +CMS_sign_receipt() creates and returns a CMS signed receipt structure. B<si> is +the B<CMS_SignerInfo> structure containing the signed receipt request. +B<signcert> is the certificate to sign with, B<pkey> is the corresponding +private key. B<certs> is an optional additional set of certificates to include +in the CMS structure (for example any intermediate CAs in the chain). + +B<flags> is an optional set of flags. + +=head1 NOTES + +This functions behaves in a similar way to CMS_sign() except the flag values +B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM> +are not supported since they do not make sense in the context of signed +receipts. + +=head1 RETURN VALUES + +CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if +an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, +L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>, +L<CMS_sign(3)|CMS_sign(3)> + +=head1 HISTORY + +CMS_sign_receipt() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_uncompress.pod b/openssl/doc/crypto/CMS_uncompress.pod new file mode 100644 index 000000000..c6056b027 --- /dev/null +++ b/openssl/doc/crypto/CMS_uncompress.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + + CMS_uncompress - uncompress a CMS CompressedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags); + +=head1 DESCRIPTION + +CMS_uncompress() extracts and uncompresses the content from a CMS +CompressedData structure B<cms>. B<data> is a BIO to write the content to and +B<flags> is an optional set of flags. + +The B<dcont> parameter is used in the rare case where the compressed content +is detached. It will normally be set to NULL. + +=head1 NOTES + +The only currently supported compression algorithm is zlib: if the structure +indicates the use of any other algorithm an error is returned. + +If zlib support is not compiled into OpenSSL then CMS_uncompress() will always +return an error. + +The following flags can be passed in the B<flags> parameter. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +=head1 RETURN VALUES + +CMS_uncompress() returns either 1 for success or 0 for failure. The error can +be obtained from ERR_get_error(3) + +=head1 BUGS + +The lack of single pass processing and the need to hold all data in memory as +mentioned in CMS_verify() also applies to CMS_decompress(). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_compress(3)|CMS_compress(3)> + +=head1 HISTORY + +CMS_uncompress() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_verify.pod b/openssl/doc/crypto/CMS_verify.pod new file mode 100644 index 000000000..8f26fdab0 --- /dev/null +++ b/openssl/doc/crypto/CMS_verify.pod @@ -0,0 +1,126 @@ +=pod + +=head1 NAME + + CMS_verify - verify a CMS SignedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags); + + STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo +structure to verify. B<certs> is a set of certificates in which to search for +the signing certificate(s). B<store> is a trusted certificate store used for +chain verification. B<indata> is the detached content if the content is not +present in B<cms>. The content is written to B<out> if it is not NULL. + +B<flags> is an optional set of flags, which can be used to modify the verify +operation. + +CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must +be called after a successful CMS_verify() operation. + +=head1 VERIFY PROCESS + +Normally the verify process proceeds as follows. + +Initially some sanity checks are performed on B<cms>. The type of B<cms> must +be SignedData. There must be at least one signature on the data and if +the content is detached B<indata> cannot be B<NULL>. + +An attempt is made to locate all the signing certificate(s), first looking in +the B<certs> parameter (if it is not NULL) and then looking in any +certificates contained in the B<cms> structure itself. If any signing +certificate cannot be located the operation fails. + +Each signing certificate is chain verified using the B<smimesign> purpose and +the supplied trusted certificate store. Any internal certificates in the message +are used as untrusted CAs. If CRL checking is enabled in B<store> any internal +CRLs are used in addition to attempting to look them up in B<store>. If any +chain verify fails an error code is returned. + +Finally the signed content is read (and written to B<out> is it is not NULL) +and the signature's checked. + +If all signature's verify correctly then the function is successful. + +Any of the following flags (ored together) can be passed in the B<flags> +parameter to change the default verify behaviour. + +If B<CMS_NOINTERN> is set the certificates in the message itself are not +searched when locating the signing certificate(s). This means that all the +signing certificates must be in the B<certs> parameter. + +If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any +CRLs in the message itself are ignored. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not +verified. + +If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not +verified. + +If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. + +=head1 NOTES + +One application of B<CMS_NOINTERN> is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the B<certs> parameter. In this case if the signer is not one of the +certificates supplied in B<certs> then the verify will fail because the +signer cannot be found. + +In some cases the standard techniques for looking up and validating +certificates are not appropriate: for example an application may wish to +lookup certificates in a database or perform customised verification. This +can be achieved by setting and verifying the signers certificates manually +using the signed data utility functions. + +Care should be taken when modifying the default verify behaviour, for example +setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification +and any modified content will be considered valid. This combination is however +useful if one merely wishes to write the content to B<out> and its validity +is not considered important. + +Chain verification should arguably be performed using the signing time rather +than the current time. However since the signing time is supplied by the +signer it cannot be trusted without additional evidence (such as a trusted +timestamp). + +=head1 RETURN VALUES + +CMS_verify() returns 1 for a successful verification and zero if an error +occurred. + +CMS_get0_signers() returns all signers or NULL if an error occurred. + +The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 BUGS + +The trusted certificate store is not searched for the signing certificate, +this is primarily due to the inadequacies of the current B<X509_STORE> +functionality. + +The lack of single pass processing means that the signed content must all +be held in memory if it is not detached. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)> + +=head1 HISTORY + +CMS_verify() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CMS_verify_receipt.pod b/openssl/doc/crypto/CMS_verify_receipt.pod new file mode 100644 index 000000000..9283e0e04 --- /dev/null +++ b/openssl/doc/crypto/CMS_verify_receipt.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + + CMS_verify_receipt - verify a CMS signed receipt + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags); + +=head1 DESCRIPTION + +CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed +receipt to verify. B<ocms> is the original SignedData structure containing the +receipt request. B<certs> is a set of certificates in which to search for the +signing certificate. B<store> is a trusted certificate store (used for chain +verification). + +B<flags> is an optional set of flags, which can be used to modify the verify +operation. + +=head1 NOTES + +This functions behaves in a similar way to CMS_verify() except the flag values +B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> are not +supported since they do not make sense in the context of signed receipts. + +=head1 RETURN VALUES + +CMS_verify_receipt() returns 1 for a successful verification and zero if an +error occurred. + +The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, +L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, +L<CMS_verify(3)|CMS_verify(3)>, + +=head1 HISTORY + +CMS_verify_receipt() was added to OpenSSL 0.9.8 + +=cut diff --git a/openssl/doc/crypto/CRYPTO_set_ex_data.pod b/openssl/doc/crypto/CRYPTO_set_ex_data.pod index 1bd5bed67..7409c02aa 100644 --- a/openssl/doc/crypto/CRYPTO_set_ex_data.pod +++ b/openssl/doc/crypto/CRYPTO_set_ex_data.pod @@ -6,6 +6,8 @@ CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data func =head1 SYNOPSIS + #include <openssl/crypto.h> + int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); diff --git a/openssl/doc/crypto/DSA_get_ex_new_index.pod b/openssl/doc/crypto/DSA_get_ex_new_index.pod index 4612e708e..fb6efc118 100644 --- a/openssl/doc/crypto/DSA_get_ex_new_index.pod +++ b/openssl/doc/crypto/DSA_get_ex_new_index.pod @@ -6,7 +6,7 @@ DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specifi =head1 SYNOPSIS - #include <openssl/DSA.h> + #include <openssl/dsa.h> int DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, diff --git a/openssl/doc/crypto/EVP_DigestInit.pod b/openssl/doc/crypto/EVP_DigestInit.pod index 130cd7f60..5b477ac6e 100644 --- a/openssl/doc/crypto/EVP_DigestInit.pod +++ b/openssl/doc/crypto/EVP_DigestInit.pod @@ -64,9 +64,9 @@ EVP digest routines The EVP digest routines are a high level interface to message digests. -EVP_MD_CTX_init() initializes digest contet B<ctx>. +EVP_MD_CTX_init() initializes digest context B<ctx>. -EVP_MD_CTX_create() allocates, initializes and returns a digest contet. +EVP_MD_CTX_create() allocates, initializes and returns a digest context. EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this @@ -102,7 +102,7 @@ the passed context B<ctx> does not have to be initialized, and it always uses the default digest implementation. EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest -contet B<ctx> is automatically cleaned up. +context B<ctx> is automatically cleaned up. EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to be initialized. @@ -132,7 +132,9 @@ return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 dige algorithms respectively. The associated signature algorithm is RSA in each case. EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest -algorithms but using DSS (DSA) for the signature algorithm. +algorithms but using DSS (DSA) for the signature algorithm. Note: there is +no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are +however retained for compatibility. EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it returns is of zero length. @@ -228,12 +230,6 @@ digest name passed on the command line. printf("\n"); } -=head1 BUGS - -The link between digests and signing algorithms results in a situation where -EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS -even though they are identical digests. - =head1 SEE ALSO L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, @@ -253,4 +249,11 @@ EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were changed to return truely const EVP_MD * in OpenSSL 0.9.7. +The link between digests and signing algorithms was fixed in OpenSSL 1.0 and +later, so now EVP_sha1() can be used with RSA and DSA, there is no need to +use EVP_dss1() any more. + +OpenSSL 1.0 and later does not include the MD2 digest algorithm in the +default configuration due to its security weaknesses. + =cut diff --git a/openssl/doc/crypto/EVP_DigestSignInit.pod b/openssl/doc/crypto/EVP_DigestSignInit.pod new file mode 100644 index 000000000..37d960e3b --- /dev/null +++ b/openssl/doc/crypto/EVP_DigestSignInit.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital signatures. + +EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from +ENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with +EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the +EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can +be used to set alternative signing options. + +EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the +signature context B<ctx>. This function can be called several times on the +same B<ctx> to include additional data. This function is currently implemented +usig a macro. + +EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>. +If B<sig> is B<NULL> then the maximum size of the output buffer is written to +the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the +B<siglen> parameter should contain the length of the B<sig> buffer, if the +call is successful the signature is written to B<sig> and the amount of data +written to B<siglen>. + +=head1 RETURN VALUES + +EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return +1 for success and 0 or a negative value for failure. In particular a return +value of -2 indicates the operation is not supported by the public key +algorithm. + +The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as EVP_dss1() +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. + +For some key types and parameters the random number generator must be seeded +or the operation will fail. + +The call to EVP_DigestSignFinal() internally finalizes a copy of the digest +context. This means that calls to EVP_DigestSignUpdate() and +EVP_DigestSignFinal() can be called later to digest and sign additional data. + +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak +will occur. + +The use of EVP_PKEY_size() with these functions is discouraged because some +signature operations may have a signature length which depends on the +parameters set. As a result EVP_PKEY_size() would have to return a value +which indicates the maximum possible signature for any set of parameters. + +=head1 SEE ALSO + +L<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>, +L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, +L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> + +=head1 HISTORY + +EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() +were first added to OpenSSL 1.0.0. + +=cut diff --git a/openssl/doc/crypto/EVP_DigestVerifyInit.pod b/openssl/doc/crypto/EVP_DigestVerifyInit.pod new file mode 100644 index 000000000..f22448897 --- /dev/null +++ b/openssl/doc/crypto/EVP_DigestVerifyInit.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signature verification functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital signatures. + +EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest +B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be initialized +with EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the +EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this +can be used to set alternative verification options. + +EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the +verification context B<ctx>. This function can be called several times on the +same B<ctx> to include additional data. This function is currently implemented +using a macro. + +EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in +B<sig> of length B<siglen>. + +=head1 RETURN VALUES + +EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 indicates +the operation is not supported by the public key algorithm. + +Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only +indicates that the signature did not not verify successfully (that is tbs did +not match the original data or the signature was of invalid form) it is not an +indication of a more serious error. + +The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as EVP_dss1() +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. + +For some key types and parameters the random number generator must be seeded +or the operation will fail. + +The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest +context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can +be called later to digest and verify additional data. + +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak +will occur. + +=head1 SEE ALSO + +L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, +L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, +L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> + +=head1 HISTORY + +EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() +were first added to OpenSSL 1.0.0. + +=cut diff --git a/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod b/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod new file mode 100644 index 000000000..f2f455990 --- /dev/null +++ b/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +EVP_PKEY_ctrl, EVP_PKEY_ctrl_str - algorithm specific control operations + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, + int cmd, int p1, void *p2); + int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, + const char *value); + + int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); + + #include <openssl/rsa.h> + + int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + + int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); + int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); + int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); + + #include <openssl/dsa.h> + int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); + + #include <openssl/dh.h> + int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); + + #include <openssl/ec.h> + int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); + +=head1 DESCRIPTION + +The function EVP_PKEY_CTX_ctrl() sends a control operation to the context +B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter +B<optype> is a mask indicating which operations the control can be applied to. +The control command is indicated in B<cmd> and any additional arguments in +B<p1> and B<p2>. + +Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will +instead call one of the algorithm specific macros below. + +The function EVP_PKEY_ctrl_str() allows an application to send an algorithm +specific control operation to a context B<ctx> in string form. This is +intended to be used for options specified on the command line or in text +files. The commands supported are documented in the openssl utility +command line pages for the option B<-pkeyopt> which is supported by the +B<pkeyutl>, B<genpkey> and B<req> commands. + +All the remaining "functions" are implemented as macros. + +The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used +in a signature. It can be used with any public key algorithm supporting +signature operations. + +The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>. +The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, +RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, +RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), +RSA_X931_PADDING for X9.31 padding (signature operations only) and +RSA_PKCS1_PSS_PADDING (sign and verify only). + +Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() +is used. If this macro is called for PKCS#1 padding the plaintext buffer is +an actual digest value and is encapsulated in a DigestInfo structure according +to PKCS#1 when signing and this structure is expected (and stripped off) when +verifying. If this control is not used with RSA and PKCS#1 padding then the +supplied data is used directly and not encapsulated. In the case of X9.31 +padding for RSA the algorithm identifier byte is added or checked and removed +if this control is called. If it is not called then the first byte of the plaintext buffer is expected to be the algorithm identifier byte. + +The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to +B<len> as its name implies it is only supported for PSS padding. Two special +values are supported: -1 sets the salt length to the digest length. When +signing -2 sets the salt length to the maximum permissible value. When +verifying -2 causes the salt length to be automatically determined based on the +B<PSS> block structure. If this macro is not called a salt length value of -2 +is used by default. + +The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for +RSA key genration to B<bits>. If not specified 1024 bits is used. + +The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value +for RSA key generation to B<pubexp> currently it should be an odd integer. The +B<pubexp> pointer is used internally by this function so it should not be +modified or free after the call. If this macro is not called then 65537 is used. + +The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used +for DSA parameter generation to B<bits>. If not specified 1024 is used. + +The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH +prime parameter B<p> 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<gen> +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<nid>. 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> + +=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 <openssl/evp.h> + + 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<pkey> and ENGINE B<e>. + +The EVP_PKEY_CTX_new_id() function allocates public key algorithm context +using the algorithm specified by B<id> and ENGINE B<e>. It is normally used +when no B<EVP_PKEY> 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<ctx>. + +EVP_PKEY_CTX_free() frees up the context B<ctx>. + +=head1 NOTES + +The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used +by the OpenSSL high level public key API. Contexts B<MUST NOT> 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<EVP_PKEY_CTX> structure of B<NULL> if an error occurred. + +EVP_PKEY_CTX_free() does not return a value. + +=head1 SEE ALSO + +L<EVP_PKEY_new(3)|EVP_PKEY_new(3)> + +=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 <openssl/evp.h> + + 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<pkey> 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<from> to key B<to>. + +The funcion EVP_PKEY_cmp_parameters() compares the parameters of keys +B<a> and B<b>. + +The funcion EVP_PKEY_cmp() compares the public key components and paramters +(if present) of keys B<a> and B<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<pkey> 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> + +=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 <openssl/evp.h> + + 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<pkey> for a decryption operation. + +The EVP_PKEY_decrypt() function performs a public key decryption operation +using B<ctx>. The data to be decrypted is specified using the B<in> and +B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output +buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then +before the call the B<outlen> parameter should contain the length of the +B<out> buffer, if the call is successful the decrypted data is written to +B<out> and the amount of data written to B<outlen>. + +=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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> + +=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 <openssl/evp.h> + + 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<pkey> 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<ctx>. +If B<key> is B<NULL> then the maximum size of the output buffer is written to +the B<keylen> parameter. If B<key> is not B<NULL> then before the call the +B<keylen> parameter should contain the length of the B<key> buffer, if the call +is successful the shared secret is written to B<key> and the amount of data +written to B<keylen>. + +=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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, + +=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 <openssl/evp.h> + + 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<pkey> for an encryption operation. + +The EVP_PKEY_encrypt() function performs a public key encryption operation +using B<ctx>. The data to be encrypted is specified using the B<in> and +B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output +buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then +before the call the B<outlen> parameter should contain the length of the +B<out> buffer, if the call is successful the encrypted data is written to +B<out> and the amount of data written to B<outlen>. + +=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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> + +=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 <openssl/evp.h> + int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); + +=head1 DESCRIPTION + +The EVP_PKEY_get_default_digest_nid() function sets B<pnid> to the default +message digest NID for the public key signature operations associated with key +B<pkey>. + +=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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, + +=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 <openssl/evp.h> + + 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<pkey> for a key genration operation. + +The EVP_PKEY_keygen() function performs a key generation operation, the +generated key is written to B<ppkey>. + +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<cb>. 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<idx> 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<idx> 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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> + +=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 <openssl/evp.h> + + 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<pkey> respectively. The key is sent to BIO B<out> in human readable +form. The parameter B<indent> indicated how far the printout should be indented. + +The B<pctx> parameter allows the print output to be finely tuned by using +ASN1 printing options. If B<pctx> is set to NULL then default values will +be used. + +=head1 NOTES + +Currently no public key algorithms include any options in the B<pctx> 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> + +=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 <openssl/evp.h> + + 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<pkey> for a signing operation. + +The EVP_PKEY_sign() function performs a public key signing operation +using B<ctx>. The data to be signed is specified using the B<tbs> and +B<tbslen> parameters. If B<sig> is B<NULL> then the maximum size of the output +buffer is written to the B<siglen> parameter. If B<sig> is not B<NULL> then +before the call the B<siglen> parameter should contain the length of the +B<sig> buffer, if the call is successful the signature is written to +B<sig> and the amount of data written to B<siglen>. + +=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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> + +=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 <openssl/evp.h> + + 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<pkey> for a signature verification operation. + +The EVP_PKEY_verify() function performs a public key verification operation +using B<ctx>. The signature is specified using the B<sig> and +B<siglen> parameters. The verified data (i.e. the data believed originally +signed) is specified using the B<tbs> and B<tbslen> 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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> + +=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 <openssl/evp.h> + + 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<pkey> for a verify recover operation. + +The EVP_PKEY_verifyrecover() function recovers signed data +using B<ctx>. The signature is specified using the B<sig> and +B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output +buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then +before the call the B<routlen> parameter should contain the length of the +B<rout> buffer, if the call is successful recovered data is written to +B<rout> and the amount of data written to B<routlen>. + +=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 <openssl/evp.h> + #include <openssl/rsa.h> + + 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<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> + +=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<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, 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<evp(3)|evp(3)>, 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 <openssl/objects.h> + 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 <openssl/cms.h> + #include <openssl/pem.h> + + 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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> +L<CMS_decrypt(3)|CMS_decrypt(3)>, +L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, +L<i2d_CMS_bio_stream(3)|i2d_CMS_bio_stream(3)> + +=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 <openssl/pkcs7.h> + #include <openssl/pem.h> + + 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<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, +L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, +L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, +L<i2d_PKCS7_bio_stream(3)|i2d_PKCS7_bio_stream(3)> + +=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<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> -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<NULL> a new STACK will be allocated. +The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> 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<NULL> a new STACK will be allocated. -The B<friendlyName> and B<localKeyID> attributes (if present) on each certificate -will be stored in the B<alias> and B<keyid> attributes of the B<X509> structure. +The B<friendlyName> and B<localKeyID> attributes (if present) on each +certificate will be stored in the B<alias> and B<keyid> attributes of the +B<X509> structure. + +=head1 RETURN VALUES + +PKCS12_parse() returns 1 for success and zero if an error occurred. + +The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> =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<friendlyName> and B<localKeyID> attributes are currently stored in certificates. -Other attributes are discarded. +Only B<friendlyName> and B<localKeyID> attributes are currently stored in +certificates. Other attributes are discarded. -Attributes currently cannot be store in the private key B<EVP_PKEY> structure. +Attributes currently cannot be stored in the private key B<EVP_PKEY> 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 <openssl/pkcs7.h> + + 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 <openssl/pkcs7.h> + + PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags); =head1 DESCRIPTION @@ -16,43 +18,55 @@ B<cipher> is the symmetric cipher to use. B<flags> 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<cipher> parameter must support ASN1 encoding of its -parameters. +The algorithm passed in the B<cipher> 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<flags> parameter. -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended -to the data. +If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are +prepended to the data. -Normally the supplied content is translated into MIME canonical format (as required -by the S/MIME specifications) if B<PKCS7_BINARY> 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<PKCS7_BINARY> is set then B<PKCS7_TEXT> is ignored. +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<PKCS7_BINARY> 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<PKCS7_BINARY> is set then +B<PKCS7_TEXT> is ignored. -=head1 RETURN VALUES +If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output +suitable for streaming I/O: no data is read from the BIO B<in>. -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<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> +complete and outputting its contents via a function that does not +properly finalize the B<PKCS7> 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<BIO> 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<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> =head1 HISTORY PKCS7_decrypt() was added to OpenSSL 0.9.5 +The B<PKCS7_STREAM> 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 <openssl/pkcs7.h> + + 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<signcert> -is the certificate to sign with, B<pkey> is the corresponsding private key. -B<certs> 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<signcert> is +the certificate to sign with, B<pkey> is the corresponsding private key. +B<certs> 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<data>. @@ -21,72 +23,83 @@ B<flags> is an optional set of flags. =head1 NOTES -Any of the following flags (ored together) can be passed in the B<flags> parameter. +Any of the following flags (ored together) can be passed in the B<flags> +parameter. Many S/MIME clients expect the signed content to include valid MIME headers. If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended to the data. If B<PKCS7_NOCERTS> 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<signcert> -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<PKCS7_DETACHED> -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<signcert> 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<PKCS7_DETACHED> 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<PKCS7_BINARY> 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<PKCS7_NOATTR> is set then no +authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> 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<PKCS7_BINARY> 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<PKCS7_NOATTR> is set then no authenticatedAttributes -will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are -omitted. +If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is +just initialized ready to perform the signing operation. The signing is however +B<not> performed and the data to be signed is not read from the B<data> +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<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to +which additional signers and capabilities can be added before finalization. -If the flags B<PKCS7_PARTSIGN> is set then the returned B<PKCS7> structure -is just initialized ready to perform the signing operation. The signing -is however B<not> performed and the data to be signed is not read from -the B<data> 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<PKCS7_DETACHED> B<must> also be set. =head1 NOTES -Currently the flag B<PKCS7_PARTSIGN> is only supported for detached -data. If this flag is set the returned B<PKCS7> structure is B<not> -complete and outputting its contents via a function that does not -properly finalize the B<PKCS7> structure will give unpredictable -results. +If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> +complete and outputting its contents via a function that does not properly +finalize the B<PKCS7> 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<BIO> 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<SHA1> for both RSA and DSA keys. + +In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be +B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added +using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> 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<signcert> and B<pkey> 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<signcert> and B<pkey> parameters must +B<NOT> be NULL. -When the signed data is not detached it will be stored in memory within the -B<PKCS7> 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<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> PKCS7_sign() was added to OpenSSL 0.9.5 -The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8 +The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0 + +The B<PKCS7_STREAM> 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 <openssl/pkcs7.h> + + 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<signcert> and private +key B<pkey> using message digest B<md> to a PKCS7 signed data structure +B<p7>. + +The PKCS7 structure should be obtained from an initial call to PKCS7_sign() +with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7 +signed data structure. + +If the B<md> parameter is B<NULL> then the default digest for the public +key algorithm will be used. + +Unless the B<PKCS7_REUSE_DIGEST> 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<flags> +parameter. + +If B<PKCS7_REUSE_DIGEST> 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<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the +B<PKCS7_SIGNER_INO> 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<PKCS7_NOCERTS> 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<signcert> 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<PKCS7_NOATTR> is set then no +authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> 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<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, +L<PKCS7_final(3)|PKCS7_final(3)>, + +=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 <openssl/pkcs7.h> -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 <openssl/cms.h> + + CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont); + +=head1 DESCRIPTION + +SMIME_read_CMS() parses a message in S/MIME format. + +B<in> 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<CMS_DETACHED> flag set. + +Otherwise the type of the returned structure can be determined +using CMS_get0_type(). + +To support future functionality if B<bcont> 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<CMS_ContentInfo> structure or B<NULL> +if an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_type(3)|CMS_type(3)> +L<SMIME_read_CMS(3)|SMIME_read_CMS(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> +L<CMS_decrypt(3)|CMS_decrypt(3)> + +=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 <openssl/pkcs7.h> + + 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 <openssl/cms.h> + + 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<out> is the BIO to write the data to. B<cms> is the appropriate +B<CMS_ContentInfo> structure. If streaming is enabled then the content must be +supplied in the B<data> argument. B<flags> is an optional set of flags. + +=head1 NOTES + +The following flags can be passed in the B<flags> parameter. + +If B<CMS_DETACHED> is set then cleartext signing will be used, this option only +makes sense for SignedData where B<CMS_DETACHED> is also set when CMS_sign() is +called. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to +the content, this only makes sense if B<CMS_DETACHED> is also set. + +If the B<CMS_STREAM> flag is set streaming is performed. This flag should only +be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo +creation function. + +If cleartext signing is being used and B<CMS_STREAM> 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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> +L<CMS_decrypt(3)|CMS_decrypt(3)> + +=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 <openssl/pkcs7.h> + + 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<out> is the BIO to write the data to. B<p7> is the appropriate -B<PKCS7> structure. If cleartext signing (B<multipart/signed>) is -being used then the signed data must be supplied in the B<data> -argument. B<flags> is an optional set of flags. +B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7> +structure. If streaming is enabled then the content must be supplied in the +B<data> argument. B<flags> is an optional set of flags. =head1 NOTES @@ -30,15 +31,18 @@ If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are added to the content, this only makes sense if B<PKCS7_DETACHED> is also set. -If the B<PKCS7_PARTSIGN> flag is set the signed data is finalized -and output along with the content. This flag should only be set -if B<PKCS7_DETACHED> is also set and the previous call to PKCS7_sign() -also set these flags. +If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should +only be set if B<PKCS7_STREAM> was also set in the previous call to +PKCS7_sign() or B<PKCS7_encrypt()>. -If cleartext signing is being used and B<PKCS7_PARTSIGN> not set then +If cleartext signing is being used and B<PKCS7_STREAM> 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 <openssl/x509.h> -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 <openssl/x509.h> -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 <openssl/x509.h> -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 <openssl/x509.h> + #include <openssl/x509_vfy.h> + + 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<ctx>, see +the B<ERROR CODES> section for a full description of all error codes. + +X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. 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<depth> 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<ctx> which +caused the error or B<NULL> 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<not> successful the returned chain may be incomplete or invalid. The +returned chain persists after the B<ctx> 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<n>. + +=head1 RETURN VALUES + +X509_STORE_CTX_get_error() returns B<X509_V_OK> 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<NULL> if no certificate is relevant to the error. + +X509_verify_cert_error_string() returns a human readable error string for +verification error B<n>. + +=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<X509_V_OK: ok> + +the operation was successful. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> + +the issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. + +=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> + +the CRL of a certificate could not be found. + +=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> + +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<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> + +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<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> + +the public key in the certificate SubjectPublicKeyInfo could not be read. + +=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> + +the signature of the certificate is invalid. + +=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> + +the signature of the certificate is invalid. + +=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> + +the certificate is not yet valid: the notBefore date is after the current time. + +=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> + +the certificate has expired: that is the notAfter date is before the current time. + +=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> + +the CRL is not yet valid. + +=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> + +the CRL has expired. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> + +the certificate notBefore field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> + +the certificate notAfter field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> + +the CRL lastUpdate field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> + +the CRL nextUpdate field contains an invalid time. + +=item B<X509_V_ERR_OUT_OF_MEM: out of memory> + +an error occurred trying to allocate memory. This should never happen. + +=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> + +the passed certificate is self signed and the same certificate cannot be found +in the list of trusted certificates. + +=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> + +the certificate chain could be built up using the untrusted certificates but +the root could not be found locally. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> + +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<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> + +no signatures could be verified because the chain contains only one certificate +and it is not self signed. + +=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> + +the certificate chain length is greater than the supplied maximum depth. Unused. + +=item B<X509_V_ERR_CERT_REVOKED: certificate revoked> + +the certificate has been revoked. + +=item B<X509_V_ERR_INVALID_CA: invalid CA certificate> + +a CA certificate is invalid. Either it is not a CA or its extensions are not +consistent with the supplied purpose. + +=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> + +the basicConstraints pathlength parameter has been exceeded. + +=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> + +the supplied certificate cannot be used for the specified purpose. + +=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> + +the root CA is not marked as trusted for the specified purpose. + +=item B<X509_V_ERR_CERT_REJECTED: certificate rejected> + +the root CA is marked to reject the specified purpose. + +=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> + +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<not> in itself an error. + +=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> + +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<not> in itself an error. + +=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> + +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<not> in itself an error. + +=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> + +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<not> in itself +an error. + +=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension> + +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. + + +=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension> + +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<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> + +The verification flags were set to require and explicit policy but none was +present. + +=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> + +The only CRLs that could be found did not match the scope of the certificate. + +=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> + +Some feature of a certificate extension is not supported. Unused. + +=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> + +A name constraint violation occured in the permitted subtrees. + +=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> + +A name constraint violation occured in the excluded subtrees. + +=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported> + +A certificate name constraints extension included a minimum or maximum field: +this is not supported. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type> + +An unsupported name constraint type was encountered. OpenSSL currently only +supports directory name, DNS name, email and URI types. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax> + +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<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> + +An error occured when attempting to verify the CRL path. This error can only +happen if extended CRL checking is enabled. + +=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> + +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<X509_VERIFY_CTX> structure. + +In versions of OpenSSL before 1.0 the current certificate returned by +X509_STORE_CTX_get_current_cert() was never B<NULL>. 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<X509_verify_cert(3)|X509_verify_cert(3)> + +=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 <openssl/x509_vfy.h> + + 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<RSA_get_ex_new_index(3)>. + +=head1 NOTES + +This mechanism is used internally by the B<ssl> library to store the B<SSL> +structure associated with a verification operation in an B<X509_STORE_CTX> +structure. + +=head1 SEE ALSO + +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)> + +=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 <openssl/x509_vfy.h> + + 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<X509_STORE_CTX> structure for subsequent use +by X509_verify_cert(). + +X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure. + +X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. +The context can then be reused with an new call to X509_STORE_CTX_init(). + +X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx> +is no longer valid. + +X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation. +The trusted certificate store is set to B<store>, the end entity certificate +to be verified is set to B<x509> and a set of additional certificates (which +will be untrusted but may be used to build the chain) in B<chain>. Any or +all of the B<store>, B<x509> and B<chain> parameters can be B<NULL>. + +X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B<ctx> +to B<sk>. This is an alternative way of specifying trusted certificates +instead of using an B<X509_STORE>. + +X509_STORE_CTX_set_cert() sets the certificate to be vertified in B<ctx> to +B<x>. + +X509_STORE_CTX_set_chain() sets the additional certificate chain used by B<ctx> +to B<sk>. + +X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate +verification to B<sk>. These CRLs will only be used if CRL verification is +enabled in the associated B<X509_VERIFY_PARAM> 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<ctx>. + +X509_STORE_CTX_set0_param() sets the intenal verification parameter pointer +to B<param>. After this call B<param> should not be used. + +X509_STORE_CTX_set_default() looks up and sets the default verification +method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to +find an appropriate set of parameters from B<name>. + +=head1 NOTES + +The certificates and CRLs in a store are used internally and should B<not> +be freed up until after the associated B<X509_STORE_CTX> is freed. Legacy +applications might implicitly use an B<X509_STORE_CTX> like this: + + X509_STORE_CTX ctx; + X509_STORE_CTX_init(&ctx, store, cert, chain); + +this is B<not> 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<not> +be freed up until after the associated B<X509_STORE_CTX> 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<NULL> 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<X509_VERIFY_PARAM> +structure or B<NULL> 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<X509_verify_cert(3)|X509_verify_cert(3)> +L<X509_VERIFY_PARAM_set_flags(3)|X509_VERIFY_PARAM_set_flags(3)> + +=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 <openssl/x509_vfy.h> + + 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<ctx> to +B<verify_cb> 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<not> essential and the default operation +is often sufficient. + +The B<ok> 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<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the +policy checking is complete. + +The B<ctx> parameter to the callback is the B<X509_STORE_CTX> 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<ex_data> mechanism. + +=head1 WARNING + +In general a verification callback should B<NOT> 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<any> 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<X509_STORE_CTX> structure is created and destroyed internally and the +only way to set a custom verification callback is by inheriting it from the +associated B<X509_STORE>. + +=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<any> 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<bio_err> is assumed to be +a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using +B<ex_data>. + + 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, "<no cert>\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<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> +L<X509_STORE_set_verify_cb_func(3)|X509_STORE_set_verify_cb_func(3)> +L<X509_STORE_CTX_get_ex_new_index(3)|X509_STORE_CTX_get_ex_new_index(3)> + +=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 <openssl/x509_vfy.h> + + 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<ctx> to +B<verify_cb> 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<X509_STORE> is inherited by +the corresponding B<X509_STORE_CTX> structure when it is initialized. This can +be used to set the verification callback when the B<X509_STORE_CTX> 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<X509_STORE_CTX_set_verify_cb(3)|X509_STORE_CTX_set_verify_cb(3)> +L<CMS_verify(3)|CMS_verify(3)> + +=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 <openssl/x509_vfy.h> + + 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<X509_VERIFY_PARAM> structure associated with +a certificate verification operation. + +The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring +it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete +description of values the B<flags> parameter can take. + +X509_VERIFY_PARAM_get_flags() returns the flags in B<param>. + +X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>. + +X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param> +to B<purpose>. 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<param> to +B<trust>. + +X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to +B<t>. Normally the current time is used. + +X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled +by default) and adds B<policy> 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<policies>. Any existing +policy set is cleared. The B<policies> parameter can be B<NULL> to clear +an existing policy set. + +X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. +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<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf +certificate. An error occurs if a suitable CRL cannot be found. + +B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate +chain. + +B<X509_V_FLAG_IGNORE_CRITICAL> 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<WARNING> 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<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken +certificates and makes the verification strictly apply B<X509> rules. + +B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification. + +B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default +no policy checking is peformed. Additional information is sent to the +verification callback relating to policy checking. + +B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and +B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any +policy> and B<inhibit policy mapping> flags respectively as defined in +B<RFC3280>. Policy checking is automatically enabled if any of these flags +are set. + +If B<X509_V_FLAG_NOTIFY_POLICY> 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<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set +they are enabled. + +If B<X509_V_FLAG_USE_DELTAS> ise set delta CRLs (if present) are used to +determine certificate status. If not set deltas are ignored. + +B<X509_V_FLAG_CHECK_SS_SIGNATURE> 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<X509_V_FLAG_CB_ISSUER_CHECK> flag enables debugging of certificate +issuer checks. It is B<not> 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<must> 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<X509_STORE>) constructed CRLs are not +maintained. + +If CRLs checking is enable CRLs are expected to be available in the +corresponding B<X509_STORE> 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<SSL_CTX> structure B<ctx>: + + 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<X509_verify_cert(3)|X509_verify_cert(3)> + +=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 <openssl/x509.h> + 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 <openssl/x509.h> + + 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<ctx>. A complete description of +the process is contained in the L<verify(1)|verify(1)> 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<ctx> 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<ctx> (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<x509.h> as opposed to most chain verification +functiosn which use B<x509_vfy.h>. + +=head1 SEE ALSO + +L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> + +=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 <openssl/bn.h> + 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<d>, a malloc()ed array of words (B<BN_ULONG>), least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits in size, depending on the 'number of bits' (B<BITS2>) specified in C<openssl/bn.h>. -B<max> is the size of the B<d> array that has been allocated. B<top> +B<dmax> is the size of the B<d> array that has been allocated. B<top> is the number of words being used, so for a value of 4, bn.d[0]=4 and bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is B<0>, the B<d> field can be B<NULL> and B<top> == B<0>. +B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The +flags begin with B<BN_FLG_>. The macros BN_set_flags(b,n) and +BN_get_flags(b,n) exist to enable or fetch flag(s) B<n> from B<BIGNUM> +structure B<b>. + Various routines in this library require the use of temporary B<BIGNUM> variables during their execution. Since dynamic memory allocation to create B<BIGNUM>s is rather expensive when used in @@ -207,12 +219,12 @@ significant non-zero word plus one when B<a> has shrunk. =head2 Debugging bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top -E<lt>= (a)-E<gt>max)>. A violation will cause the program to abort. +E<lt>= (a)-E<gt>dmax)>. A violation will cause the program to abort. bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d> (in reverse order, i.e. most significant word first) to stderr. -bn_set_max() makes B<a> a static number with a B<max> of its current size. +bn_set_max() makes B<a> a static number with a B<dmax> of its current size. This is used by bn_set_low() and bn_set_high() to make B<r> a read-only B<BIGNUM> that contains the B<n> low or high words of B<a>. 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 <openssl/rsa.h> #include <openssl/x509.h> - 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<X509> structure or B<NULL> if an error occurs. The error code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. -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<ERR_get_error(3)|ERR_get_error(3)>. +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<ERR_get_error(3)|ERR_get_error(3)>. -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<ERR_get_error(3)|ERR_get_error(3)>. =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 B<EVP_Encrypt>I<...> functions. The B<EVP_Digest>I<...> functions provide message digests. +The B<EVP_PKEY>I<...> 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<md> is NULL, the digest is placed in a static array. The size of the output is placed in B<md_len>, unless it is B<NULL>. B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. -B<key> and B<evp_md> may be B<NULL> if a key and hash function have -been set in a previous call to HMAC_Init() for that B<HMAC_CTX>. HMAC_CTX_init() initialises a B<HMAC_CTX> 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 <openssl/cms.h> + + 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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> +L<CMS_decrypt(3)|CMS_decrypt(3)>, +L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, +L<PEM_write_bio_CMS_stream(3)|PEM_write_bio_CMS_stream(3)> + +=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 <openssl/pkcs7.h> + + 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<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, +L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, +L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, +L<PEM_write_bio_PKCS7_stream(3)|PEM_write_bio_PKCS7_stream(3)> + +=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 <openssl/lhash.h> - LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare); - void lh_free(LHASH *table); + DECLARE_LHASH_OF(<type>); - void *lh_insert(LHASH *table, void *data); - void *lh_delete(LHASH *table, void *data); - void *lh_retrieve(LHASH *table, void *data); + LHASH *lh_<type>_new(); + void lh_<type>_free(LHASH_OF(<type> *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); + <type> *lh_<type>_insert(LHASH_OF(<type> *table, <type> *data); + <type> *lh_<type>_delete(LHASH_OF(<type> *table, <type> *data); + <type> *lh_retrieve(LHASH_OF<type> *table, <type> *data); - int lh_error(LHASH *table); + void lh_<type>_doall(LHASH_OF(<type> *table, LHASH_DOALL_FN_TYPE func); + void lh_<type>_doall_arg(LHASH_OF(<type> *table, LHASH_DOALL_ARG_FN_TYPE func, + <type2>, <type2> *arg); + + int lh_<type>_error(LHASH_OF(<type> *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<LHASH> structure to store arbitrary data -entries, and provides the 'hash' and 'compare' callbacks to be used in -organising the table's entries. The B<hash> 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<compare> 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<hash> and B<compare> callbacks hash/compare -these types, then the B<DECLARE_LHASH_HASH_FN> and -B<IMPLEMENT_LHASH_COMP_FN> 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_<type>_new() creates a new B<LHASH_OF(<type>> structure to store +arbitrary data entries, and provides the 'hash' and 'compare' +callbacks to be used in organising the table's entries. The B<hash> +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<compare> 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<hash> and +B<compare> callbacks hash/compare these types, then the +B<DECLARE_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be +used to create callback wrappers of the prototypes required by +lh_<type>_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<LHASH> structure B<table>. Allocated hash table -entries will not be freed; consider using lh_doall() to deallocate any -remaining entries in the hash table (see below). +lh_<type>_free() frees the B<LHASH_OF(<type>> structure +B<table>. Allocated hash table entries will not be freed; consider +using lh_<type>_doall() to deallocate any remaining entries in the +hash table (see below). -lh_insert() inserts the structure pointed to by B<data> into B<table>. -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_<type>_insert() inserts the structure pointed to by B<data> into +B<table>. If there already is an entry with the same key, the old +value is replaced. Note that lh_<type>_insert() stores pointers, the +data are not copied. -lh_delete() deletes an entry from B<table>. +lh_<type>_delete() deletes an entry from B<table>. -lh_retrieve() looks up an entry in B<table>. Normally, B<data> is -a structure with the key field(s) set; the function will return a +lh_<type>_retrieve() looks up an entry in B<table>. Normally, B<data> +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<func> 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<NOTE>) - 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_<type>_doall() will, for every entry in the hash table, call +B<func> with the data item as its parameter. For lh_<type>_doall() +and lh_<type>_doall_arg(), function pointer casting should be avoided +in the callbacks (see B<NOTE>) - 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<func> will be -called with B<arg> as the second argument and B<func> should be of -type B<LHASH_DOALL_ARG_FN_TYPE> (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_<type>_doall_arg() is the same as lh_<type>_doall() except that +B<func> will be called with B<arg> as the second argument and B<func> +should be of type B<LHASH_DOALL_ARG_FN_TYPE> (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_<type>_error() can be used to determine if an error occurred in the last +operation. lh_<type>_error() is a macro. =head1 RETURN VALUES -lh_new() returns B<NULL> on error, otherwise a pointer to the new +lh_<type>_new() returns B<NULL> on error, otherwise a pointer to the new B<LHASH> structure. -When a hash table entry is replaced, lh_insert() returns the value +When a hash table entry is replaced, lh_<type>_insert() returns the value being replaced. B<NULL> is returned on normal operation and on error. -lh_delete() returns the entry being deleted. B<NULL> is returned if +lh_<type>_delete() returns the entry being deleted. B<NULL> 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_<type>_retrieve() returns the hash table entry if it has been found, B<NULL> otherwise. -lh_error() returns 1 if an error occurred in the last operation, 0 +lh_<type>_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_<type>_free(), lh_<type>_doall() and lh_<type>_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<NULL> both for success and error. +lh_<type>_insert() returns B<NULL> 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<LHASH> 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_<type>_new(), rather it would be +used in the function passed to lh_<type>_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 <openssl/crypto.h> - 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<CRYPTO_LOCK>, and releases it otherwise. B<file> and B<line> 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<id>. The implementation of this callback should not +fill in B<id> 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<errno>. 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<id> 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<crypto/threads/mttest.c> 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<CRYPTO_THREADID> 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 <openssl/des_old.h> + 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 <openssl/ssl.h> - 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<options> to B<ctx>. Options already set before are not cleared! SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. Options already set before are not cleared! +SSL_CTX_clear_options() clears the options set via bitmask in B<options> +to B<ctx>. + +SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>. + SSL_CTX_get_options() returns the options set for B<ctx>. SSL_get_options() returns the options set for B<ssl>. +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<or> -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<SECURE RENEGOTIATION> section for more details. + +=item SSL_OP_LEGACY_SERVER_CONNECT + +Allow legacy insecure renegotiation between OpenSSL and unpatched servers +B<only>: this option is currently set by default. See the +B<SECURE RENEGOTIATION> 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<strongly> 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<patched>. A server not supporting secure +renegotiation is referred to as I<unpatched>. + +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<no_renegotiation> warning alert if TLS v1.0 is used or a fatal +B<handshake_failure> alert in SSL v3.0. + +If the patched OpenSSL server attempts to renegotiate a fatal +B<handshake_failure> alert is sent. This is because the server code may be +unaware of the unpatched nature of the client. + +If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then +renegotiation B<always> succeeds. + +B<NB:> 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<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard +a B<no_renegotiation> alert as fatal and respond with a fatal +B<handshake_failure> 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<SSL_OP_LEGACY_SERVER_CONNECT> or +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> 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<SSL_OP_LEGACY_SERVER_CONNECT> 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<SSL_OP_LEGACY_SERVER_CONNECT> will +B<not> 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<set> B<SSL_OP_LEGACY_SERVER_CONNECT> + +OpenSSL client applications that want to ensure they can B<not> connect to +unpatched servers (and thus avoid any security issues) should always B<clear> +B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or +SSL_clear_options(). + +The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that +B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure +renegotiation between OpenSSL clients and unpatched servers B<only>, while +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> 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<options>. +SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask +after clearing B<options>. + 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<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, @@ -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<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT> +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 <openssl/ssl.h> + + 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<ssl>, a B<NULL>-terminated PSK identity hint +sent by the server in parameter B<hint>, a buffer B<identity> of +length B<max_identity_len> bytes where the the resulting +B<NULL>-terminated identity is to be stored, and a buffer B<psk> of +length B<max_psk_len> bytes where the resulting pre-shared key is to +be stored. + +=head1 NOTES + +Note that parameter B<hint> given to the callback may be B<NULL>. + +=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<psk> 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 <openssl/ssl.h> - 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 <openssl/ssl.h> + + 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<NULL>-terminated PSK +identity hint B<hint> to SSL context object +B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated +PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint> +is B<NULL> the current hint from B<ctx> or B<ssl> is deleted. + +In the case where PSK identity hint is B<NULL>, 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<ssl>, B<NULL>-terminated PSK identity sent +by the client in parameter B<identity>, and a buffer B<psk> of length +B<max_psk_len> 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<psk>. Return value is the length of +B<psk> in bytes. It is an error to return a value greater than +B<max_psk_len>. + +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<psk> 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 <openssl/ssl.h> + + 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<ssl>. Similarly, SSL_get_psk_identity() is used to retrieve the PSK +identity used during the connection setup. + + +=head1 RETURN VALUES + +If non-B<NULL>, SSL_get_psk_identity_hint() returns the PSK identity +hint and SSL_get_psk_identity() returns the PSK identity. Both are +B<NULL>-terminated. SSL_get_psk_identity_hint() may return B<NULL> 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<ssl>. + +=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<SSL_METHOD> structures. =over 4 -=item SSL_METHOD *B<SSLv2_client_method>(void); +=item const SSL_METHOD *B<SSLv2_client_method>(void); Constructor for the SSLv2 SSL_METHOD structure for a dedicated client. -=item SSL_METHOD *B<SSLv2_server_method>(void); +=item const SSL_METHOD *B<SSLv2_server_method>(void); Constructor for the SSLv2 SSL_METHOD structure for a dedicated server. -=item SSL_METHOD *B<SSLv2_method>(void); +=item const SSL_METHOD *B<SSLv2_method>(void); Constructor for the SSLv2 SSL_METHOD structure for combined client and server. -=item SSL_METHOD *B<SSLv3_client_method>(void); +=item const SSL_METHOD *B<SSLv3_client_method>(void); Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. -=item SSL_METHOD *B<SSLv3_server_method>(void); +=item const SSL_METHOD *B<SSLv3_server_method>(void); Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. -=item SSL_METHOD *B<SSLv3_method>(void); +=item const SSL_METHOD *B<SSLv3_method>(void); Constructor for the SSLv3 SSL_METHOD structure for combined client and server. -=item SSL_METHOD *B<TLSv1_client_method>(void); +=item const SSL_METHOD *B<TLSv1_client_method>(void); Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. -=item SSL_METHOD *B<TLSv1_server_method>(void); +=item cosnt SSL_METHOD *B<TLSv1_server_method>(void); Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. -=item SSL_METHOD *B<TLSv1_method>(void); +=item const SSL_METHOD *B<TLSv1_method>(void); Constructor for the TLSv1 SSL_METHOD structure for combined client and server. @@ -249,7 +249,7 @@ protocol context defined in the B<SSL_CTX> structure. =item long B<SSL_CTX_need_tmp_RSA>(SSL_CTX *ctx); -=item SSL_CTX *B<SSL_CTX_new>(SSL_METHOD *meth); +=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth); =item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c); @@ -327,7 +327,7 @@ protocol context defined in the B<SSL_CTX> structure. =item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode); -=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, SSL_METHOD *meth); +=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth); =item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t); @@ -374,6 +374,15 @@ session instead of a context. =item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, char *file, int type); +=item void B<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)); + +=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint); + +=item void B<SSL_CTX_set_psk_server_callback>(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<SSL> structure. =item int B<SSL_get_shutdown>(const SSL *ssl); -=item SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); +=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); =item int B<SSL_get_state>(const SSL *ssl); @@ -596,7 +605,7 @@ connection defined in the B<SSL> structure. =item void B<SSL_set_shutdown>(SSL *ssl, int mode); -=item int B<SSL_set_ssl_method>(SSL *ssl, SSL_METHOD *meth); +=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth); =item void B<SSL_set_time>(SSL *ssl, long t); @@ -650,6 +659,16 @@ connection defined in the B<SSL> structure. =item int B<SSL_write>(SSL *ssl, const void *buf, int num); +=item void B<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)); + +=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint); + +=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); + +=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl); + +=item const char *B<SSL_get_psk_identity>(SSL *ssl); + =back =head1 SEE ALSO @@ -726,7 +745,10 @@ L<SSL_write(3)|SSL_write(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>, L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, -L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> +L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, +L<SSL_CTX_set_psk_client_callback(3)|SSL_CTX_set_psk_client_callback(3)>, +L<SSL_CTX_use_psk_identity_hint(3)|SSL_CTX_use_psk_identity_hint(3)>, +L<SSL_get_psk_identity(3)|SSL_get_psk_identity(3)> =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) |