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

. + +=item B + +The value to use for the generator B. + +=back + +=head1 EC PARAMETER GENERATION OPTIONS + +=over 4 + +=item B + +the EC curve to use. + +=back + +=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS + +Gost 2001 support is not enabled by default. To enable this algorithm, +one should load the ccgost engine in the OpenSSL configuration file. +See README.gost file in the engines/ccgost directiry of the source +distribution for more details. + +Use of a parameter file for the GOST R 34.10 algorithm is optional. +Parameters can be specified during key generation directly as well as +during generation of parameter file. + +=over 4 + +=item B + +Specifies GOST R 34.10-2001 parameter set according to RFC 4357. +Parameter set can be specified using abbreviated name, object short name or +numeric OID. Following parameter sets are supported: + + paramset OID Usage + A 1.2.643.2.2.35.1 Signature + B 1.2.643.2.2.35.2 Signature + C 1.2.643.2.2.35.3 Signature + XA 1.2.643.2.2.36.0 Key exchange + XB 1.2.643.2.2.36.1 Key exchange + test 1.2.643.2.2.35.0 Test purposes + +=back + + + +=head1 NOTES + +The use of the genpkey program is encouraged over the algorithm specific +utilities because additional algorithm options and ENGINE provided algorithms +can be used. + +=head1 EXAMPLES + +Generate an RSA private key using default parameters: + + openssl genpkey -algorithm RSA -out key.pem + +Encrypt output private key using 128 bit AES and the passphrase "hello": + + openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello + +Generate a 2048 bit RSA key using 3 as the public exponent: + + openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \ + -pkeyopt rsa_keygen_pubexp:3 + +Generate 1024 bit DSA parameters: + + openssl genpkey -genparam -algorithm DSA -out dsap.pem \ + -pkeyopt dsa_paramgen_bits:1024 + +Generate DSA key from parameters: + + openssl genpkey -paramfile dsap.pem -out dsakey.pem + +Generate 1024 bit DH parameters: + + openssl genpkey -genparam -algorithm DH -out dhp.pem \ + -pkeyopt dh_paramgen_prime_len:1024 + +Generate DH key from parameters: + + openssl genpkey -paramfile dhp.pem -out dhkey.pem + + +=cut + diff --git a/openssl/doc/apps/genrsa.pod b/openssl/doc/apps/genrsa.pod index 25af4d147..7dcac2a77 100644 --- a/openssl/doc/apps/genrsa.pod +++ b/openssl/doc/apps/genrsa.pod @@ -57,7 +57,7 @@ all others. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/ocsp.pod b/openssl/doc/apps/ocsp.pod index b58ddc178..af2e12e41 100644 --- a/openssl/doc/apps/ocsp.pod +++ b/openssl/doc/apps/ocsp.pod @@ -51,6 +51,7 @@ B B [B<-ndays n>] [B<-resp_key_id>] [B<-nrequest n>] +[B<-md5|-sha1|...>] =head1 DESCRIPTION @@ -206,6 +207,11 @@ information is immediately available. In this case the age of the B f is checked to see it is not older than B seconds old. By default this additional check is not performed. +=item B<-md5|-sha1|-sha256|-ripemod160|...> + +this option sets digest algorithm to use for certificate identification +in the OCSP request. By default SHA-1 is used. + =back =head1 OCSP SERVER OPTIONS diff --git a/openssl/doc/apps/openssl.pod b/openssl/doc/apps/openssl.pod index 964cdf0f0..738142e9f 100644 --- a/openssl/doc/apps/openssl.pod +++ b/openssl/doc/apps/openssl.pod @@ -12,7 +12,7 @@ I [ I ] [ I ] -B [ B | B | B ] +B [ B | B | B | B | B | B] B BI [ I ] @@ -26,12 +26,14 @@ The B program is a command line tool for using the various cryptography functions of OpenSSL's B library from the shell. It can be used for - o Creation of RSA, DH and DSA key parameters + o Creation and management of private keys, public keys and parameters + o Public key cryptographic operations o Creation of X.509 certificates, CSRs and CRLs o Calculation of Message Digests o Encryption and Decryption with Ciphers o SSL/TLS Client and Server Tests o Handling of S/MIME signed or encrypted mail + o Time Stamp requests, generation and verification =head1 COMMAND SUMMARY @@ -44,6 +46,14 @@ and B output a list (one entry per line) of the names of all standard commands, message digest commands, or cipher commands, respectively, that are available in the present B utility. +The pseudo-commands B and +B list all cipher and message digest names, one entry per line. Aliases are listed as: + + from => to + +The pseudo-command B lists all supported public +key algorithms. + The pseudo-command BI tests whether a command of the specified name is available. If no command named I exists, it returns 0 (success) and prints BI; otherwise it returns 1 @@ -71,6 +81,10 @@ Certificate Authority (CA) Management. Cipher Suite Description Determination. +=item L|cms(1)> + +CMS (Cryptographic Message Syntax) utility + =item L|crl(1)> Certificate Revocation List (CRL) Management. @@ -88,25 +102,40 @@ Message Digest Calculation. Diffie-Hellman Parameter Management. Obsoleted by L|dhparam(1)>. +=item L|dhparam(1)> + +Generation and Management of Diffie-Hellman Parameters. Superseded by +L|genpkey(1)> and L|pkeyparam(1)> + + =item L|dsa(1)> DSA Data Management. =item L|dsaparam(1)> -DSA Parameter Generation. +DSA Parameter Generation and Management. Superseded by +L|genpkey(1)> and L|pkeyparam(1)> + +=item L|ec(1)> + +EC (Elliptic curve) key processing + +=item L|ecparam(1)> + +EC parameter manipulation and generation =item L|enc(1)> Encoding with Ciphers. -=item L|errstr(1)> +=item L|engine(1)> -Error Number to Error String Conversion. +Engine (loadble module) information and manipulation. -=item L|dhparam(1)> +=item L|errstr(1)> -Generation and Management of Diffie-Hellman Parameters. +Error Number to Error String Conversion. =item B @@ -115,11 +144,20 @@ Obsoleted by L|dhparam(1)>. =item L|gendsa(1)> -Generation of DSA Parameters. +Generation of DSA Private Key from Parameters. Superseded by +L|genpkey(1)> and L|pkey(1)> + +=item L|genpkey(1)> + +Generation of Private Key or Parameters. =item L|genrsa(1)> -Generation of RSA Parameters. +Generation of RSA Private Key. Superceded by L|genpkey(1)>. + +=item L|nseq(1)> + +Create or examine a netscape certificate sequence =item L|ocsp(1)> @@ -137,21 +175,35 @@ PKCS#12 Data Management. PKCS#7 Data Management. +=item L|pkey(1)> + +Public and private key management. + +=item L|pkeyparam(1)> + +Public key algorithm parameter management. + +=item L|pkeyutl(1)> + +Public key algorithm cryptographic operation utility. + =item L|rand(1)> Generate pseudo-random bytes. =item L|req(1)> -X.509 Certificate Signing Request (CSR) Management. +PKCS#10 X.509 Certificate Signing Request (CSR) Management. =item L|rsa(1)> -RSA Data Management. +RSA key management. + =item L|rsautl(1)> -RSA utility for signing, verification, encryption, and decryption. +RSA utility for signing, verification, encryption, and decryption. Superseded +by L|pkeyutl(1)> =item L|s_client(1)> @@ -185,6 +237,14 @@ S/MIME mail processing. Algorithm Speed Measurement. +=item L|spkac(1)> + +SPKAC printing and generating utility + +=item L|ts(1)> + +Time Stamping Authority tool (client/server) + =item L|verify(1)> X.509 Certificate Verification. @@ -227,6 +287,8 @@ SHA Digest SHA-1 Digest +=back + =item B SHA-224 Digest @@ -243,8 +305,6 @@ SHA-384 Digest SHA-512 Digest -=back - =head2 ENCODING AND CIPHER COMMANDS =over 10 @@ -339,7 +399,7 @@ read the password from standard input. L, L, L, L, L, L, L, L, L, -L, L, +L, L, L, L, L, L, L, L, L, L, @@ -348,12 +408,13 @@ L, L, L, L, L, L, L, L, L, -L, L +L, L, L =head1 HISTORY The openssl(1) document appeared in OpenSSL 0.9.2. The BIB<-commands> pseudo-commands were added in OpenSSL 0.9.3; +The BIB<-algorithms> pseudo-commands were added in OpenSSL 1.0.0; the BI pseudo-commands were added in OpenSSL 0.9.5a. For notes on the availability of other commands, see their individual manual pages. diff --git a/openssl/doc/apps/pkcs12.pod b/openssl/doc/apps/pkcs12.pod index 7d8414629..f69a5c5a4 100644 --- a/openssl/doc/apps/pkcs12.pod +++ b/openssl/doc/apps/pkcs12.pod @@ -23,22 +23,23 @@ B B [B<-cacerts>] [B<-nokeys>] [B<-info>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-nodes>] +[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>] [B<-noiter>] -[B<-maciter>] +[B<-maciter | -nomaciter | -nomac>] [B<-twopass>] [B<-descert>] -[B<-certpbe>] -[B<-keypbe>] +[B<-certpbe cipher>] +[B<-keypbe cipher>] +[B<-macalg digest>] [B<-keyex>] [B<-keysig>] [B<-password arg>] [B<-passin arg>] [B<-passout arg>] [B<-rand file(s)>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-CSP name>] =head1 DESCRIPTION @@ -49,7 +50,7 @@ programs including Netscape, MSIE and MS Outlook. =head1 COMMAND OPTIONS There are a lot of options the meaning of some depends of whether a PKCS#12 file -is being created or parsed. By default a PKCS#12 file is parsed a PKCS#12 +is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 file can be created by using the B<-export> option (see below). =head1 PARSING OPTIONS @@ -63,25 +64,25 @@ by default. =item B<-out filename> -The filename to write certificates and private keys to, standard output by default. -They are all written in PEM format. +The filename to write certificates and private keys to, standard output by +default. They are all written in PEM format. =item B<-pass arg>, B<-passin arg> -the PKCS#12 file (i.e. input file) password source. For more information about the -format of B see the B section in +the PKCS#12 file (i.e. input file) password source. For more information about +the format of B see the B section in L. =item B<-passout arg> -pass phrase source to encrypt any outputed private keys with. For more information -about the format of B see the B section in -L. +pass phrase source to encrypt any outputed private keys with. For more +information about the format of B see the B section +in L. =item B<-noout> -this option inhibits output of the keys and certificates to the output file version -of the PKCS#12 file. +this option inhibits output of the keys and certificates to the output file +version of the PKCS#12 file. =item B<-clcerts> @@ -116,6 +117,14 @@ use triple DES to encrypt private keys before outputting, this is the default. use IDEA to encrypt private keys before outputting. +=item B<-aes128>, B<-aes192>, B<-aes256> + +use AES to encrypt private keys before outputting. + +=item B<-camellia128>, B<-camellia192>, B<-camellia256> + +use Camellia to encrypt private keys before outputting. + =item B<-nodes> don't encrypt the private keys at all. @@ -148,10 +157,10 @@ by default. =item B<-in filename> -The filename to read certificates and private keys from, standard input by default. -They must all be in PEM format. The order doesn't matter but one private key and -its corresponding certificate should be present. If additional certificates are -present they will also be included in the PKCS#12 file. +The filename to read certificates and private keys from, standard input by +default. They must all be in PEM format. The order doesn't matter but one +private key and its corresponding certificate should be present. If additional +certificates are present they will also be included in the PKCS#12 file. =item B<-inkey filename> @@ -160,8 +169,8 @@ in the input file. =item B<-name friendlyname> -This specifies the "friendly name" for the certificate and private key. This name -is typically displayed in list boxes by software importing the file. +This specifies the "friendly name" for the certificate and private key. This +name is typically displayed in list boxes by software importing the file. =item B<-certfile filename> @@ -201,9 +210,11 @@ key is encrypted using triple DES and the certificate using 40 bit RC2. =item B<-keypbe alg>, B<-certpbe alg> these options allow the algorithm used to encrypt the private key and -certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms -can be selected it is advisable only to use PKCS#12 algorithms. See the list -in the B section for more information. +certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name +can be used (see B section for more information). If a a cipher name +(as output by the B command is specified then it +is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only +use PKCS#12 algorithms. =item B<-keyex|-keysig> @@ -216,6 +227,10 @@ S/MIME signing, authenticode (ActiveX control signing) and SSL client authentication, however due to a bug only MSIE 5.0 and later support the use of signing only keys for SSL client authentication. +=item B<-macalg digest> + +specify the MAC digest algorithm. If not included them SHA1 will be used. + =item B<-nomaciter>, B<-noiter> these options affect the iteration counts on the MAC and key algorithms. @@ -239,6 +254,10 @@ option. This option is included for compatibility with previous versions, it used to be needed to use MAC iterations counts but they are now used by default. +=item B<-nomac> + +don't attempt to provide the MAC integrity. + =item B<-rand file(s)> a file or files containing random data used to seed the random number @@ -247,6 +266,20 @@ Multiple files can be specified separated by a OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. +=item B<-CAfile file> + +CA storage as a file. + +=item B<-CApath dir> + +CA storage as a directory. This directory must be a standard certificate +directory: that is a hash of each subject name (using B) should be +linked to each certificate. + +=item B<-CSP name> + +write B as a Microsoft CSP name. + =back =head1 NOTES diff --git a/openssl/doc/apps/pkcs7.pod b/openssl/doc/apps/pkcs7.pod index a0a636328..acfb8100f 100644 --- a/openssl/doc/apps/pkcs7.pod +++ b/openssl/doc/apps/pkcs7.pod @@ -62,7 +62,7 @@ is B<-print_certs> is set). =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/pkcs8.pod b/openssl/doc/apps/pkcs8.pod index 68ecd65b1..84abee78f 100644 --- a/openssl/doc/apps/pkcs8.pod +++ b/openssl/doc/apps/pkcs8.pod @@ -125,7 +125,7 @@ list of possible algorithms is included below. =item B<-engine id> -specifying an engine (by it's unique B string) will cause B +specifying an engine (by its unique B string) will cause B to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. diff --git a/openssl/doc/apps/pkey.pod b/openssl/doc/apps/pkey.pod new file mode 100644 index 000000000..4851223f3 --- /dev/null +++ b/openssl/doc/apps/pkey.pod @@ -0,0 +1,135 @@ + +=pod + +=head1 NAME + +pkey - public or private key processing tool + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-cipher>] +[B<-text>] +[B<-text_pub>] +[B<-noout>] +[B<-pubin>] +[B<-pubout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B command processes public or private keys. They can be converted +between various forms and their components printed out. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format DER or PEM. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a key from or standard input if this +option is not specified. If the key is encrypted a pass phrase will be +prompted for. + +=item B<-passin arg> + +the input file password source. For more information about the format of B +see the B section in L. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output if this +option is not specified. If any encryption options are set then a pass phrase +will be prompted for. The output filename should B be the same as the input +filename. + +=item B<-passout password> + +the output file password source. For more information about the format of B +see the B section in L. + +=item B<-cipher> + +These options encrypt the private key with the supplied cipher. Any algorithm +name accepted by EVP_get_cipherbyname() is acceptable such as B. + +=item B<-text> + +prints out the various public or private key components in +plain text in addition to the encoded version. + +=item B<-text_pub> + +print out only public key components even if a private key is being processed. + +=item B<-noout> + +do not output the encoded version of the key. + +=item B<-pubin> + +by default a private key is read from the input file: with this +option a public key is read instead. + +=item B<-pubout> + +by default a private key is output: with this option a public +key will be output instead. This option is automatically set if +the input is a public key. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLES + +To remove the pass phrase on an RSA private key: + + openssl pkey -in key.pem -out keyout.pem + +To encrypt a private key using triple DES: + + openssl pkey -in key.pem -des3 -out keyout.pem + +To convert a private key from PEM to DER format: + + openssl pkey -in key.pem -outform DER -out keyout.der + +To print out the components of a private key to standard output: + + openssl pkey -in key.pem -text -noout + +To print out the public components of a private key to standard output: + + openssl pkey -in key.pem -text_pub -noout + +To just output the public part of a private key: + + openssl pkey -in key.pem -pubout -out pubkey.pem + +=head1 SEE ALSO + +L, L, L, +L, L, L + +=cut diff --git a/openssl/doc/apps/pkeyparam.pod b/openssl/doc/apps/pkeyparam.pod new file mode 100644 index 000000000..154f6721a --- /dev/null +++ b/openssl/doc/apps/pkeyparam.pod @@ -0,0 +1,69 @@ + +=pod + +=head1 NAME + +pkeyparam - public key algorithm parameter processing tool + +=head1 SYNOPSIS + +B B +[B<-in filename>] +[B<-out filename>] +[B<-text>] +[B<-noout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B command processes public or private keys. They can be converted +between various forms and their components printed out. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. + +=item B<-out filename> + +This specifies the output filename to write parameters to or standard output if +this option is not specified. + +=item B<-text> + +prints out the parameters in plain text in addition to the encoded version. + +=item B<-noout> + +do not output the encoded version of the parameters. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLE + +Print out text version of parameters: + + openssl pkeyparam -in param.pem -text + +=head1 NOTES + +There are no B<-inform> or B<-outform> options for this command because only +PEM format is supported because the key type is determined by the PEM headers. + +=head1 SEE ALSO + +L, L, L, +L, L, L + +=cut diff --git a/openssl/doc/apps/pkeyutl.pod b/openssl/doc/apps/pkeyutl.pod new file mode 100644 index 000000000..27be9a900 --- /dev/null +++ b/openssl/doc/apps/pkeyutl.pod @@ -0,0 +1,222 @@ +=pod + +=head1 NAME + +pkeyutl - public key algorithm utility + +=head1 SYNOPSIS + +B B +[B<-in file>] +[B<-out file>] +[B<-sigfile file>] +[B<-inkey file>] +[B<-keyform PEM|DER>] +[B<-passin arg>] +[B<-peerkey file>] +[B<-peerform PEM|DER>] +[B<-pubin>] +[B<-certin>] +[B<-rev>] +[B<-sign>] +[B<-verify>] +[B<-verifyrecover>] +[B<-encrypt>] +[B<-decrypt>] +[B<-derive>] +[B<-pkeyopt opt:value>] +[B<-hexdump>] +[B<-asn1parse>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B command can be used to perform public key operations using +any supported algorithm. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies the input filename to read data from or standard input +if this option is not specified. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-inkey file> + +the input key file, by default it should be a private key. + +=item B<-keyform PEM|DER> + +the key format PEM, DER or ENGINE. + +=item B<-passin arg> + +the input key password source. For more information about the format of B +see the B section in L. + + +=item B<-peerkey file> + +the peer key file, used by key derivation (agreement) operations. + +=item B<-peerform PEM|DER> + +the peer key format PEM, DER or ENGINE. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + + +=item B<-pubin> + +the input file is a public key. + +=item B<-certin> + +the input is a certificate containing a public key. + +=item B<-rev> + +reverse the order of the input buffer. This is useful for some libraries +(such as CryptoAPI) which represent the buffer in little endian format. + +=item B<-sign> + +sign the input data and output the signed result. This requires +a private key. + +=item B<-verify> + +verify the input data against the signature file and indicate if the +verification succeeded or failed. + +=item B<-verifyrecover> + +verify the input data and output the recovered data. + +=item B<-encrypt> + +encrypt the input data using a public key. + +=item B<-decrypt> + +decrypt the input data using a private key. + +=item B<-derive> + +derive a shared secret using the peer key. + +=item B<-hexdump> + +hex dump the output data. + +=item B<-asn1parse> + +asn1parse the output data, this is useful when combined with the +B<-verifyrecover> option when an ASN1 structure is signed. + +=back + +=head1 NOTES + +The operations and options supported vary according to the key algorithm +and its implementation. The OpenSSL operations and options are indicated below. + +Unless otherwise mentioned all algorithms support the B option +which specifies the digest in use for sign, verify and verifyrecover operations. +The value B should represent a digest name as used in the +EVP_get_digestbyname() function for example B. + +=head1 RSA ALGORITHM + +The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover +operations in general. Some padding modes only support some of these +operations however. + +=over 4 + +=item -B + +This sets the RSA padding mode. Acceptable values for B are B for +PKCS#1 padding, B for SSLv23 padding, B for no padding, B +for B mode, B for X9.31 mode and B for PSS. + +In PKCS#1 padding if the message digest is not set then the supplied data is +signed or verified directly instead of using a B structure. If a +digest is set then the a B structure is used and its the length +must correspond to the digest type. + +For B mode only encryption and decryption is supported. + +For B if the digest type is set it is used to format the block data +otherwise the first byte is used to specify the X9.31 digest ID. Sign, +verify and verifyrecover are can be performed in this mode. + +For B mode only sign and verify are supported and the digest type must be +specified. + +=item B + +For B mode only this option specifies the salt length. Two special values +are supported: -1 sets the salt length to the digest length. When signing -2 +sets the salt length to the maximum permissible value. When verifying -2 causes +the salt length to be automatically determined based on the B block +structure. + +=back + +=head1 DSA ALGORITHM + +The DSA algorithm supports signing and verification operations only. Currently +there are no additional options other than B. Only the SHA1 +digest can be used and this digest is assumed by default. + +=head1 DH ALGORITHM + +The DH algorithm only supports the derivation operation and no additional +options. + +=head1 EC ALGORITHM + +The EC algorithm supports sign, verify and derive operations. The sign and +verify operations use ECDSA and derive uses ECDH. Currently there are no +additional options other than B. Only the SHA1 digest can be used and +this digest is assumed by default. + +=head1 EXAMPLES + +Sign some data using a private key: + + openssl pkeyutl -sign -in file -inkey key.pem -out sig + +Recover the signed data (e.g. if an RSA key is used): + + openssl pkeyutl -verifyrecover -in sig -inkey key.pem + +Verify the signature (e.g. a DSA key): + + openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem + +Sign data using a message digest value (this is currently only valid for RSA): + + openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 + +Derive a shared secret value: + + openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret + +=head1 SEE ALSO + +L, L, L +L, L, L diff --git a/openssl/doc/apps/req.pod b/openssl/doc/apps/req.pod index 82b565c9d..ff48bbdf2 100644 --- a/openssl/doc/apps/req.pod +++ b/openssl/doc/apps/req.pod @@ -22,12 +22,13 @@ B B [B<-new>] [B<-rand file(s)>] [B<-newkey rsa:bits>] -[B<-newkey dsa:file>] +[B<-newkey alg:file>] [B<-nodes>] [B<-key filename>] [B<-keyform PEM|DER>] [B<-keyout filename>] -[B<-[md5|sha1|md2|mdc2]>] +[B<-keygen_engine id>] +[B<-[digest]>] [B<-config filename>] [B<-subj arg>] [B<-multivalue-rdn>] @@ -35,11 +36,15 @@ B B [B<-days n>] [B<-set_serial n>] [B<-asn1-kludge>] +[B<-no-asn1-kludge>] [B<-newhdr>] [B<-extensions section>] [B<-reqexts section>] [B<-utf8>] [B<-nameopt>] +[B<-reqopt>] +[B<-subject>] +[B<-subj arg>] [B<-batch>] [B<-verbose>] [B<-engine id>] @@ -91,6 +96,11 @@ see the B section in L. prints out the certificate request in text form. +=item B<-subject> + +prints out the request subject (or certificate subject if B<-x509> is +specified) + =item B<-pubkey> outputs the public key. @@ -118,6 +128,13 @@ in the configuration file and any requested extensions. If the B<-key> option is not used it will generate a new RSA private key using information specified in the configuration file. +=item B<-subj arg> + +Replaces subject field of input request with specified data and outputs +modified request. The arg must be formatted as +I, +characters may be escaped by \ (backslash), no spaces are skipped. + =item B<-rand file(s)> a file or files containing random data used to seed the random number @@ -129,10 +146,35 @@ all others. =item B<-newkey arg> this option creates a new certificate request and a new private -key. The argument takes one of two forms. B, where +key. The argument takes one of several forms. B, where B is the number of bits, generates an RSA key B -in size. B generates a DSA key using the parameters -in the file B. +in size. If B is omitted, i.e. B<-newkey rsa> specified, +the default key size, specified in the configuration file is used. + +All other algorithms support the B<-newkey alg:file> form, where file may be +an algorithm parameter file, created by the B command +or and X.509 certificate for a key with approriate algorithm. + +B generates a key using the parameter file or certificate B, +the algorithm is determined by the parameters. B use algorithm +B and parameter file B: the two algorithms must match or an +error occurs. B just uses algorithm B, and parameters, +if neccessary should be specified via B<-pkeyopt> parameter. + +B generates a DSA key using the parameters +in the file B. B generates EC key (usable both with +ECDSA or ECDH algorithms), B generates GOST R +34.10-2001 key (requires B engine configured in the configuration +file). If just B is specified a parameter set should be +specified by B<-pkeyopt paramset:X> + + +=item B<-pkeyopt opt:value> + +set the public key algorithm option B to B. The precise set of +options supported depends on the public key algorithm used and its +implementation. See B in the B manual page +for more details. =item B<-key filename> @@ -155,11 +197,15 @@ configuration file is used. if this option is specified then if a private key is created it will not be encrypted. -=item B<-[md5|sha1|md2|mdc2]> +=item B<-[digest]> + +this specifies the message digest to sign the request with (such as +B<-md5>, B<-sha1>). This overrides the digest algorithm specified in +the configuration file. -this specifies the message digest to sign the request with. This -overrides the digest algorithm specified in the configuration file. -This option is ignored for DSA requests: they always use SHA1. +Some public key algorithms may override this choice. For instance, DSA +signatures always use SHA1, GOST R 34.10 signatures always use +GOST R 34.11-94 (B<-md_gost94>). =item B<-config filename> @@ -227,6 +273,15 @@ B