diff options
Diffstat (limited to 'openssl/doc/apps')
34 files changed, 2756 insertions, 160 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 |