diff options
Diffstat (limited to 'crypto/openssl/doc/apps')
| -rw-r--r-- | crypto/openssl/doc/apps/CA.pl.pod | 11 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/ca.pod | 9 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/ciphers.pod | 8 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/dgst.pod | 67 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/dhparam.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/dsaparam.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/gendsa.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/genrsa.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/openssl.pod | 19 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/passwd.pod | 13 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/pkcs12.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/rand.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/req.pod | 10 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/rsa.pod | 31 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/rsautl.pod | 183 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/smime.pod | 57 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/speed.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/verify.pod | 63 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/x509.pod | 176 |
19 files changed, 620 insertions, 41 deletions
diff --git a/crypto/openssl/doc/apps/CA.pl.pod b/crypto/openssl/doc/apps/CA.pl.pod index 9d287f0..63cd132 100644 --- a/crypto/openssl/doc/apps/CA.pl.pod +++ b/crypto/openssl/doc/apps/CA.pl.pod @@ -69,9 +69,16 @@ list box), otherwise the name "My Certificate" is used. calls the B<ca> program to sign a certificate request. It expects the request to be in the file "newreq.pem". The new certificate is written to the file -"newcert.pem" except in the case of the B<-xcert> option when it is written +"newcert.pem" except in the case of the B<-xsign> option when it is written to standard output. + +=item B<-signCA> + +this option is the same as the B<-signreq> option except it uses the configuration +file section B<v3_ca> and so makes the signed request a valid CA certificate. This +is useful when creating intermediate CA from a root CA. + =item B<-signcert> this option is the same as B<-sign> except it expects a self signed certificate @@ -122,7 +129,7 @@ Create the CA directories and files: enter cacert.pem when prompted for the CA file name. -Create a DSA certificate request and privat key (a different set of parameters +Create a DSA certificate request and private key (a different set of parameters can optionally be created first): openssl req -out newreq.pem -newkey dsa:dsap.pem diff --git a/crypto/openssl/doc/apps/ca.pod b/crypto/openssl/doc/apps/ca.pod index 03209aa..d352925 100644 --- a/crypto/openssl/doc/apps/ca.pod +++ b/crypto/openssl/doc/apps/ca.pod @@ -23,6 +23,7 @@ B<openssl> B<ca> [B<-policy arg>] [B<-keyfile arg>] [B<-key arg>] +[B<-passin arg>] [B<-cert file>] [B<-in file>] [B<-out file>] @@ -99,6 +100,10 @@ the password used to encrypt the private key. Since on some systems the command line arguments are visible (e.g. Unix with the 'ps' utility) this option should be used with caution. +=item B<-passin arg> + +the 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<-verbose> this prints extra details about the operations being performed. @@ -342,6 +347,10 @@ Sign a certificate request: openssl ca -in req.pem -out newcert.pem +Sign a certificate request, using CA extensions: + + openssl ca -in req.pem -extensions v3_ca -out newcert.pem + Generate a CRL openssl ca -gencrl -out crl.pem diff --git a/crypto/openssl/doc/apps/ciphers.pod b/crypto/openssl/doc/apps/ciphers.pod index 2301e28..2107761 100644 --- a/crypto/openssl/doc/apps/ciphers.pod +++ b/crypto/openssl/doc/apps/ciphers.pod @@ -25,9 +25,13 @@ the appropriate cipherlist. =item B<-v> -verbose option. List ciphers with a complete description of the authentication, -key exchange, encryption and mac algorithms used along with any key size +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. +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<-ssl3> diff --git a/crypto/openssl/doc/apps/dgst.pod b/crypto/openssl/doc/apps/dgst.pod index fcfd3ec..1648742 100644 --- a/crypto/openssl/doc/apps/dgst.pod +++ b/crypto/openssl/doc/apps/dgst.pod @@ -2,25 +2,32 @@ =head1 NAME -dgst, md5, md2, sha1, sha, mdc2, ripemd160 - message digests +dgst, md5, md4, md2, sha1, sha, mdc2, ripemd160 - message digests =head1 SYNOPSIS B<openssl> B<dgst> -[B<-md5|-md2|-sha1|-sha|mdc2|-ripemd160>] +[B<-md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1>] [B<-c>] [B<-d>] +[B<-hex>] +[B<-binary>] +[B<-out filename>] +[B<-sign filename>] +[B<-verify filename>] +[B<-prverify filename>] +[B<-signature filename>] [B<file...>] -[B<md5|md2|sha1|sha|mdc2|ripemd160>] +[B<md5|md4|md2|sha1|sha|mdc2|ripemd160>] [B<-c>] [B<-d>] [B<file...>] =head1 DESCRIPTION -The digest functions print out the message digest of a supplied file or files -in hexadecimal form. +The digest functions output the message digest of a supplied file or files +in hexadecimal form. They can also be used for digital signing and verification. =head1 OPTIONS @@ -28,12 +35,51 @@ in hexadecimal form. =item B<-c> -print out the digest in two digit groups separated by colons. +print out the digest in two digit groups separated by colons, only relevant if +B<hex> format output is used. =item B<-d> print out BIO debugging information. +=item B<-hex> + +digest is to be output as a hex dump. This is the default case for a "normal" +digest as opposed to a digital signature. + +=item B<-binary> + +output the digest or signature in binary form. + +=item B<-out filename> + +filename to output to, or standard output by default. + +=item B<-sign filename> + +digitally sign the digest using the private key in "filename". + +=item B<-verify filename> + +verify the signature using the the public key in "filename". +The output is either "Verification OK" or "Verification Failure". + +=item B<-prverify filename> + +verify the signature using the the private key in "filename". + +=item B<-signature filename> + +the actual signature to verify. + +=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<file...> file or files to digest. If no files are specified then standard input is @@ -46,4 +92,13 @@ used. The digest of choice for all new applications is SHA1. Other digests are however still widely used. +If you wish to sign or verify data using the DSA algorithm then the dss1 +digest must be used. + +A source of random numbers is required for certain signing algorithms, in +particular DSA. + +The signing and verify options should only be used if a single file is +being signed or verified. + =cut diff --git a/crypto/openssl/doc/apps/dhparam.pod b/crypto/openssl/doc/apps/dhparam.pod index 15aabf4..ff8a6e5 100644 --- a/crypto/openssl/doc/apps/dhparam.pod +++ b/crypto/openssl/doc/apps/dhparam.pod @@ -73,7 +73,7 @@ input file is ignored and parameters are generated instead. 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 OpenVSM, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =item I<numbits> diff --git a/crypto/openssl/doc/apps/dsaparam.pod b/crypto/openssl/doc/apps/dsaparam.pod index 8647f34..50c2f61 100644 --- a/crypto/openssl/doc/apps/dsaparam.pod +++ b/crypto/openssl/doc/apps/dsaparam.pod @@ -73,7 +73,7 @@ parameters. 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 OpenVSM, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =item B<numbits> diff --git a/crypto/openssl/doc/apps/gendsa.pod b/crypto/openssl/doc/apps/gendsa.pod index 3314ace..74318fe 100644 --- a/crypto/openssl/doc/apps/gendsa.pod +++ b/crypto/openssl/doc/apps/gendsa.pod @@ -34,7 +34,7 @@ If none of these options is specified no encryption is used. 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 OpenVSM, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =item B<paramfile> diff --git a/crypto/openssl/doc/apps/genrsa.pod b/crypto/openssl/doc/apps/genrsa.pod index 70d35fe..cdcc03c 100644 --- a/crypto/openssl/doc/apps/genrsa.pod +++ b/crypto/openssl/doc/apps/genrsa.pod @@ -51,7 +51,7 @@ the public exponent to use, either 65537 or 3. The default is 65537. 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 OpenVSM, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =item B<numbits> diff --git a/crypto/openssl/doc/apps/openssl.pod b/crypto/openssl/doc/apps/openssl.pod index 2fc61b6..0cbd199 100644 --- a/crypto/openssl/doc/apps/openssl.pod +++ b/crypto/openssl/doc/apps/openssl.pod @@ -83,9 +83,10 @@ CRL to PKCS#7 Conversion. Message Digest Calculation. -=item L<B<dh>|dh(1)> +=item B<dh> -Diffie-Hellman Data Management. +Diffie-Hellman Parameter Management. +Obsoleted by L<B<dhparam>|dhparam(1)>. =item L<B<dsa>|dsa(1)> @@ -103,9 +104,14 @@ Encoding with Ciphers. Error Number to Error String Conversion. -=item L<B<gendh>|gendh(1)> +=item L<B<dhparam>|dhparam(1)> + +Generation and Management of Diffie-Hellman Parameters. + +=item B<gendh> Generation of Diffie-Hellman Parameters. +Obsoleted by L<B<dhparam>|dhparam(1)>. =item L<B<gendsa>|gendsa(1)> @@ -135,6 +141,10 @@ X.509 Certificate Signing Request (CSR) Management. RSA Data Management. +=item L<B<rsautl>|rsautl(1)> + +RSA utility for signing, verification, encryption, and decryption. + =item L<B<s_client>|s_client(1)> This implements a generic SSL/TLS client which can establish a transparent @@ -309,7 +319,8 @@ L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(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)>, -L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>, L<s_client(1)|s_client(1)>, +L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>, +L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(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)> diff --git a/crypto/openssl/doc/apps/passwd.pod b/crypto/openssl/doc/apps/passwd.pod index cee6a2f..6e09894 100644 --- a/crypto/openssl/doc/apps/passwd.pod +++ b/crypto/openssl/doc/apps/passwd.pod @@ -8,6 +8,7 @@ passwd - compute password hashes B<openssl passwd> [B<-crypt>] +[B<-1>] [B<-apr1>] [B<-salt> I<string>] [B<-in> I<file>] @@ -22,8 +23,8 @@ The B<passwd> command computes the hash of a password typed at run-time or the hash of each password in a list. The password list is taken from the named file for option B<-in file>, from stdin for option B<-stdin>, and from the command line otherwise. -The Unix standard algorithm B<crypt> and the MD5-based B<apr1> algorithm -are available. +The Unix standard algorithm B<crypt> and the MD5-based BSD password +algorithm B<1> and its Apache variant B<apr1> are available. =head1 OPTIONS @@ -33,9 +34,13 @@ are available. Use the B<crypt> algorithm (default). +=item B<-1> + +Use the MD5 based BSD password algorithm B<1>. + =item B<-apr1> -Use the B<apr1> algorithm. +Use the B<apr1> algorithm (Apache variant of the BSD algorithm). =item B<-salt> I<string> @@ -64,6 +69,8 @@ to each password hash. B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>. +B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$8XJIcl6ZXqBMCK0qFevqT1>. + B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>. =cut diff --git a/crypto/openssl/doc/apps/pkcs12.pod b/crypto/openssl/doc/apps/pkcs12.pod index 241f9c4..c400999 100644 --- a/crypto/openssl/doc/apps/pkcs12.pod +++ b/crypto/openssl/doc/apps/pkcs12.pod @@ -244,7 +244,7 @@ to be needed to use MAC iterations counts but they are now used by default. 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 OpenVSM, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =back diff --git a/crypto/openssl/doc/apps/rand.pod b/crypto/openssl/doc/apps/rand.pod index f81eab0..cbf8768 100644 --- a/crypto/openssl/doc/apps/rand.pod +++ b/crypto/openssl/doc/apps/rand.pod @@ -34,7 +34,7 @@ Write to I<file> instead of standard output. Use specified file or files or EGD socket (see L<RAND_egd(3)|RAND_egd(3)>) for seeding the random number generator. Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =item B<-base64> diff --git a/crypto/openssl/doc/apps/req.pod b/crypto/openssl/doc/apps/req.pod index fde6ff2..a3f54f4 100644 --- a/crypto/openssl/doc/apps/req.pod +++ b/crypto/openssl/doc/apps/req.pod @@ -19,6 +19,7 @@ B<openssl> B<req> [B<-verify>] [B<-modulus>] [B<-new>] +[B<-rand file(s)>] [B<-newkey rsa:bits>] [B<-newkey dsa:file>] [B<-nodes>] @@ -104,6 +105,14 @@ 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<-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<-newkey arg> this option creates a new certificate request and a new private @@ -158,6 +167,7 @@ when the B<-x509> option is being used this specifies the number of days to certify the certificate for. The default is 30 days. =item B<-extensions section> + =item B<-reqexts section> these options specify alternative sections to include certificate diff --git a/crypto/openssl/doc/apps/rsa.pod b/crypto/openssl/doc/apps/rsa.pod index 62ad62e..f0e613e 100644 --- a/crypto/openssl/doc/apps/rsa.pod +++ b/crypto/openssl/doc/apps/rsa.pod @@ -14,6 +14,7 @@ B<openssl> B<rsa> [B<-passin arg>] [B<-out filename>] [B<-passout arg>] +[B<-sgckey>] [B<-des>] [B<-des3>] [B<-idea>] @@ -42,9 +43,8 @@ This specifies the input format. The B<DER> option uses an ASN1 DER encoded form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format. The B<PEM> form is the default format: it consists of the B<DER> format base64 encoded with additional header and footer lines. On input PKCS#8 format private -keys are also accepted. The B<NET> form is a format compatible with older Netscape -servers and MS IIS, this uses unsalted RC4 for its encryption. It is not very -secure and so should only be used when necessary. +keys are also accepted. The B<NET> form is a format is described in the B<NOTES> +section. =item B<-outform DER|NET|PEM> @@ -74,6 +74,11 @@ filename. 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<-sgckey> + +use the modified NET algorithm used with some versions of Microsoft IIS and SGC +keys. + =item B<-des|-des3|-idea> These options encrypt the private key with the DES, triple DES, or the @@ -126,6 +131,18 @@ The PEM public key format uses the header and footer lines: -----BEGIN PUBLIC KEY----- -----END PUBLIC KEY----- +The B<NET> form is a format compatible with older Netscape servers +and Microsoft IIS .key files, this uses unsalted RC4 for its encryption. +It is not very secure and so should only be used when necessary. + +Some newer version of IIS have additional data in the exported .key +files. To use thse with the utility view the file with a binary editor +and look for the string "private-key", then trace back to the byte +sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data +from this point onwards to another file and use that as the input +to the B<rsa> utility with the B<-inform NET> option. If you get +an error after entering the password try the B<-sgckey> option. + =head1 EXAMPLES To remove the pass phrase on an RSA private key: @@ -148,6 +165,14 @@ To just output the public part of a private key: openssl rsa -in key.pem -pubout -out pubkey.pem +=head1 BUGS + +The command line password arguments don't currently work with +B<NET> format. + +There should be an option that automatically handles .key files, +without having to manually edit them. + =head1 SEE ALSO L<pkcs8(1)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, diff --git a/crypto/openssl/doc/apps/rsautl.pod b/crypto/openssl/doc/apps/rsautl.pod new file mode 100644 index 0000000..7a334bc --- /dev/null +++ b/crypto/openssl/doc/apps/rsautl.pod @@ -0,0 +1,183 @@ +=pod + +=head1 NAME + +rsautl - RSA utility + +=head1 SYNOPSIS + +B<openssl> B<rsautl> +[B<-in file>] +[B<-out file>] +[B<-inkey file>] +[B<-pubin>] +[B<-certin>] +[B<-sign>] +[B<-verify>] +[B<-encrypt>] +[B<-decrypt>] +[B<-pkcs>] +[B<-ssl>] +[B<-raw>] +[B<-hexdump>] +[B<-asn1parse>] + +=head1 DESCRIPTION + +The B<rsautl> command can be used to sign, verify, encrypt and decrypt +data using the RSA 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 an RSA private key. + +=item B<-pubin> + +the input file is an RSA public key. + +=item B<-certin> + +the input is a certificate containing an RSA public key. + +=item B<-sign> + +sign the input data and output the signed result. This requires +and RSA private key. + +=item B<-verify> + +verify the input data and output the recovered data. + +=item B<-encrypt> + +encrypt the input data using an RSA public key. + +=item B<-decrypt> + +decrypt the input data using an RSA private key. + +=item B<-pkcs, -oaep, -ssl, -raw> + +the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP, +special padding used in SSL v2 backwards compatible handshakes, +or no padding, respectively. +For signatures, only B<-pkcs> and B<-raw> can be used. + +=item B<-hexdump> + +hex dump the output data. + +=item B<-asn1parse> + +asn1parse the output data, this is useful when combined with the +B<-verify> option. + +=back + +=head1 NOTES + +B<rsautl> because it uses the RSA algorithm directly can only be +used to sign or verify small pieces of data. + +=head1 EXAMPLES + +Sign some data using a private key: + + openssl rsautl -sign -in file -inkey key.pem -out sig + +Recover the signed data + + openssl rsautl -sign -in sig -inkey key.pem + +Examine the raw signed data: + + openssl rsautl -sign -in file -inkey key.pem -raw -hexdump + + 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world + +The PKCS#1 block formatting is evident from this. If this was done using +encrypt and decrypt the block would have been of type 2 (the second byte) +and random padding data visible instead of the 0xff bytes. + +It is possible to analyse the signature of certificates using this +utility in conjunction with B<asn1parse>. Consider the self signed +example in certs/pca-cert.pem . Running B<asn1parse> as follows yields: + + openssl asn1parse -in pca-cert.pem + + 0:d=0 hl=4 l= 742 cons: SEQUENCE + 4:d=1 hl=4 l= 591 cons: SEQUENCE + 8:d=2 hl=2 l= 3 cons: cont [ 0 ] + 10:d=3 hl=2 l= 1 prim: INTEGER :02 + 13:d=2 hl=2 l= 1 prim: INTEGER :00 + 16:d=2 hl=2 l= 13 cons: SEQUENCE + 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption + 29:d=3 hl=2 l= 0 prim: NULL + 31:d=2 hl=2 l= 92 cons: SEQUENCE + 33:d=3 hl=2 l= 11 cons: SET + 35:d=4 hl=2 l= 9 cons: SEQUENCE + 37:d=5 hl=2 l= 3 prim: OBJECT :countryName + 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU + .... + 599:d=1 hl=2 l= 13 cons: SEQUENCE + 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption + 612:d=2 hl=2 l= 0 prim: NULL + 614:d=1 hl=3 l= 129 prim: BIT STRING + + +The final BIT STRING contains the actual signature. It can be extracted with: + + openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614 + +The certificate public key can be extracted with: + + openssl x509 -in test/testx509.pem -pubout -noout >pubkey.pem + +The signature can be analysed with: + + openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin + + 0:d=0 hl=2 l= 32 cons: SEQUENCE + 2:d=1 hl=2 l= 12 cons: SEQUENCE + 4:d=2 hl=2 l= 8 prim: OBJECT :md5 + 14:d=2 hl=2 l= 0 prim: NULL + 16:d=1 hl=2 l= 16 prim: OCTET STRING + 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%.. + +This is the parsed version of an ASN1 DigestInfo structure. It can be seen that +the digest used was md5. The actual part of the certificate that was signed can +be extracted with: + + openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4 + +and its digest computed with: + + openssl md5 -c tbs + MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5 + +which it can be seen agrees with the recovered value above. + +=head1 SEE ALSO + +L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> diff --git a/crypto/openssl/doc/apps/smime.pod b/crypto/openssl/doc/apps/smime.pod index 631ecdc..ce99b5c 100644 --- a/crypto/openssl/doc/apps/smime.pod +++ b/crypto/openssl/doc/apps/smime.pod @@ -22,8 +22,12 @@ B<openssl> B<smime> [B<-signer file>] [B<-recip file>] [B<-in file>] +[B<-inform SMIME|PEM|DER>] +[B<-passin arg>] [B<-inkey file>] [B<-out file>] +[B<-outform SMIME|PEM|DER>] +[B<-content file>] [B<-to addr>] [B<-from ad>] [B<-subject s>] @@ -74,11 +78,37 @@ takes an input message and writes out a PEM encoded PKCS#7 structure. the input message to be encrypted or signed or the MIME message to be decrypted or verified. +=item B<-inform SMIME|PEM|DER> + +this specifies the input format for the PKCS#7 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 PKCS#7 structures +instead. This currently only affects the input format of the PKCS#7 +structure, if no PKCS#7 structure is being input (for example with +B<-encrypt> or B<-sign>) this option has no effect. + =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 PKCS#7 structure. The default +is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> +format change this to write PEM and DER format PKCS#7 structures +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<-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 PKCS#7 +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 @@ -174,12 +204,17 @@ 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. +=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 OpenVSM, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =item B<cert.pem...> @@ -204,7 +239,7 @@ 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 +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. @@ -290,7 +325,7 @@ Send encrypted mail using triple DES: Sign and encrypt mail: openssl smime -sign -in ml.txt -signer my.pem -text \ - | openssl -encrypt -out mail.msg \ + | openssl smime -encrypt -out mail.msg \ -from steve@openssl.org -to someone@somewhere \ -subject "Signed and Encrypted message" -des3 user.pem @@ -301,6 +336,22 @@ Decrypt mail: openssl smime -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 smime -verify -inform PEM -in signature.pem -content content.txt + +alternatively you can base64 decode the signature and use + + openssl smime -verify -inform DER -in signature.der -content content.txt + =head1 BUGS The MIME parser isn't very clever: it seems to handle most messages that I've thrown diff --git a/crypto/openssl/doc/apps/speed.pod b/crypto/openssl/doc/apps/speed.pod index fecd9a9..77560f1 100644 --- a/crypto/openssl/doc/apps/speed.pod +++ b/crypto/openssl/doc/apps/speed.pod @@ -39,7 +39,7 @@ This command is used to test the performance of cryptographic algorithms. =head1 OPTIONS -If an option is given, B<speed> test that algorithm, otherwise all of +If any options are given, B<speed> tests those algorithms, otherwise all of the above are tested. =cut diff --git a/crypto/openssl/doc/apps/verify.pod b/crypto/openssl/doc/apps/verify.pod index 4a6572d..9045552 100644 --- a/crypto/openssl/doc/apps/verify.pod +++ b/crypto/openssl/doc/apps/verify.pod @@ -2,7 +2,7 @@ =head1 NAME -pkcs7 - PKCS#7 utility +verify - Utility to verify certificates. =head1 SYNOPSIS @@ -12,6 +12,7 @@ B<openssl> B<verify> [B<-purpose purpose>] [B<-untrusted file>] [B<-help>] +[B<-issuer_checks>] [B<-verbose>] [B<->] [certificates] @@ -57,6 +58,14 @@ prints out a usage message. print extra information about the operations being performed. +=item B<-issuer_checks> + +print out diagnostics relating to searches for the issuer certificate +of the current certificate. This shows why each candidate issuer +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<-> marks the last option. All arguments following this are assumed to be @@ -88,9 +97,21 @@ The verify operation consists of a number of separate steps. Firstly a certificate chain is built up starting from the supplied certificate and ending in the root CA. It is an error if the whole chain cannot be built -up. The chain is built up by looking up a certificate whose subject name -matches the issuer name of the current certificate. If a certificate is found -whose subject and issuer names are identical it is assumed to be the root CA. +up. The chain is built up by looking up the issuers certificate of the current +certificate. If a certificate is found which is its own issuer it is assumed +to be the root CA. + +The process of 'looking up the issuers certificate' itself involves a number +of steps. In versions of OpenSSL before 0.9.5a the first certificate whose +subject name matched the issuer of the current certificate was assumed to be +the issuers certificate. In OpenSSL 0.9.6 and later all certificates +whose subject name matches the issuer name of the current certificate are +subject to further tests. The relevant authority key identifier components +of the current certificate (if present) must match the subject key identifier +(if present) and issuer and serial number of the candidate issuer, in addition +the keyUsage extension of the candidate issuer (if present) must permit +certificate signing. + The lookup first looks in the list of untrusted certificates and if no match is found the remaining lookups are from the trusted certificates. The root CA is always looked up in the trusted certificate list: if the certificate to @@ -260,12 +281,46 @@ the root CA is not marked as trusted for the specified purpose. the root CA is marked to reject the specified purpose. +=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> + +the current candidate issuer certificate was rejected because its subject name +did not match the issuer name of the current certificate. Only displayed when +the B<-issuer_checks> option is set. + +=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> + +the current candidate issuer certificate was rejected because its subject key +identifier was present and did not match the authority key identifier current +certificate. Only displayed when the B<-issuer_checks> option is set. + +=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> + +the current candidate issuer certificate was rejected because its issuer name +and serial number was present and did not match the authority key identifier +of the current certificate. Only displayed when the B<-issuer_checks> option is set. + +=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> + +the current candidate issuer certificate was rejected because its keyUsage extension +does not permit certificate signing. + =item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> an application specific error. Unused. =back +=head1 BUGS + +Although the issuer checks are a considerably improvement over the old technique they still +suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that +trusted certificates with matching subject name must either appear in a file (as specified by the +B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only +the certificates in the file will be recognised. + +Previous versions of OpenSSL assume certificates with matching subject name are identical and +mishandled them. + =head1 SEE ALSO L<x509(1)|x509(1)> diff --git a/crypto/openssl/doc/apps/x509.pod b/crypto/openssl/doc/apps/x509.pod index e4ae546..84f76cb 100644 --- a/crypto/openssl/doc/apps/x509.pod +++ b/crypto/openssl/doc/apps/x509.pod @@ -19,6 +19,8 @@ B<openssl> B<x509> [B<-hash>] [B<-subject>] [B<-issuer>] +[B<-nameopt option>] +[B<-email>] [B<-startdate>] [B<-enddate>] [B<-purpose>] @@ -137,6 +139,16 @@ outputs the subject name. outputs the issuer name. +=item B<-nameopt option> + +option which determine how the subject or issuer names are displayed. This +option may be used more than once to set multiple options. See the B<NAME +OPTIONS> section for more information. + +=item B<-email> + +outputs the email address(es) if any. + =item B<-startdate> prints out the start date of the certificate, that is the notBefore date. @@ -330,6 +342,138 @@ specified then the extensions should either be contained in the unnamed =back +=head1 NAME OPTIONS + +The B<nameopt> command line switch determines how the subject and issuer +names are displayed. If no B<nameopt> switch is present the default "oneline" +format is used which is compatible with previous versions of OpenSSL. +Each option is described in detail below, all options can be preceded by +a B<-> to turn the option off. Only the first four will normally be used. + +=over 4 + +=item B<compat> + +use the old format. This is equivalent to specifying no name options at all. + +=item B<RFC2253> + +displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>, +B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>, +B<sep_comma_plus>, B<dn_rev> and B<sname>. + +=item B<oneline> + +a oneline format which is more readable than RFC2253. It is equivalent to +specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>, +B<dump_der>, B<use_quote>, B<sep_comma_plus_spc>, B<spc_eq> and B<sname> +options. + +=item B<multiline> + +a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, +B<spc_eq> and B<lname>. + +=item B<esc_2253> + +escape the "special" characters required by RFC2253 in a field That is +B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginnging of a string +and a space character at the beginning or end of a string. + +=item B<esc_ctrl> + +escape control characters. That is those with ASCII values less than +0x20 (space) and the delete (0x7f) character. They are escaped using the +RFC2253 \XX notation (where XX are two hex digits representing the +character value). + +=item B<esc_msb> + +escape characters with the MSB set, that is with ASCII values larger than +127. + +=item B<use_quote> + +escapes some characters by surrounding the whole string with B<"> characters, +without the option all escaping is done with the B<\> character. + +=item B<utf8> + +convert all strings to UTF8 format first. This is required by RFC2253. If +you are lucky enough to have a UTF8 compatible terminal then the use +of this option (and B<not> setting B<esc_msb>) may result in the correct +display of multibyte (international) characters. Is this option is not +present then multibyte characters larger than 0xff will be represented +using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits. +Also if this option is off any UTF8Strings will be converted to their +character form first. + +=item B<no_type> + +this option does not attempt to interpret multibyte characters in any +way. That is their content octets are merely dumped as though one octet +represents each character. This is useful for diagnostic purposes but +will result in rather odd looking output. + +=item B<show_type> + +show the type of the ASN1 character string. The type precedes the +field contents. For example "BMPSTRING: Hello World". + +=item B<dump_der> + +when this option is set any fields that need to be hexdumped will +be dumped using the DER encoding of the field. Otherwise just the +content octets will be displayed. Both options use the RFC2253 +B<#XXXX...> format. + +=item B<dump_nostr> + +dump non character string types (for example OCTET STRING) if this +option is not set then non character string types will be displayed +as though each content octet repesents a single character. + +=item B<dump_all> + +dump all fields. This option when used with B<dump_der> allows the +DER encoding of the structure to be unambiguously determined. + +=item B<dump_unknown> + +dump any field whose OID is not recognised by OpenSSL. + +=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>, +B<sep_multiline> + +these options determine the field separators. The first character is +between RDNs and the second between multiple AVAs (multiple AVAs are +very rare and their use is discouraged). The options ending in +"space" additionally place a space after the separator to make it +more readable. The B<sep_multiline> uses a linefeed character for +the RDN separator and a spaced B<+> for the AVA separator. It also +indents the fields by four characters. + +=item B<dn_rev> + +reverse the fields of the DN. This is required by RFC2253. As a side +effect this also reverses the order of multiple AVAs but this is +permissible. + +=item B<nofname>, B<sname>, B<lname>, B<oid> + +these options alter how the field name is displayed. B<nofname> does +not display the field at all. B<sname> uses the "short name" form +(CN for commonName for example). B<lname> uses the long form. +B<oid> represents the OID in numerical form and is useful for +diagnostic purpose. + +=item B<spc_eq> + +places spaces round the B<=> character which follows the field +name. + +=back + =head1 EXAMPLES Note: in these examples the '\' means the example should be all on one @@ -343,6 +487,19 @@ Display the certificate serial number: openssl x509 -in cert.pem -noout -serial +Display the certificate subject name: + + openssl x509 -in cert.pem -noout -subject + +Display the certificate subject name in RFC2253 form: + + openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 + +Display the certificate subject name in oneline form on a terminal +supporting UTF8: + + openssl x509 -in cert.pem -noout -subject -nameopt oneline -nameopt -escmsb + Display the certificate MD5 fingerprint: openssl x509 -in cert.pem -noout -fingerprint @@ -362,13 +519,13 @@ Convert a certificate to a certificate request: Convert a certificate request into a self signed certificate using extensions for a CA: - openssl x509 -req -in careq.pem -config openssl.cnf -extensions v3_ca \ + openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \ -signkey key.pem -out cacert.pem Sign a certificate request using the CA certificate above and add user certificate extensions: - openssl x509 -req -in req.pem -config openssl.cnf -extensions v3_usr \ + openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \ -CA cacert.pem -CAkey key.pem -CAcreateserial @@ -395,6 +552,11 @@ Trusted certificates have the lines -----BEGIN TRUSTED CERTIFICATE---- -----END TRUSTED CERTIFICATE---- +The conversion to UTF8 format used with the name options assumes that +T61Strings use the ISO8859-1 character set. This is wrong but Netscape +and MSIE do this as do many certificates. So although this is incorrect +it is more likely to display the majority of certificates correctly. + The B<-fingerprint> option takes the digest of the DER encoded certificate. This is commonly called a "fingerprint". Because of the nature of message digests the fingerprint of a certificate is unique to that certificate and @@ -402,6 +564,10 @@ two certificates with the same fingerprint can be considered to be the same. The Netscape fingerprint uses MD5 whereas MSIE uses SHA1. +The B<-email> option searches the subject name and the subject alternative +name extension. Only unique email addresses will be printed out: it will +not print the same address more than once. + =head1 CERTIFICATE EXTENSIONS The B<-purpose> option checks the certificate extensions and determines @@ -517,10 +683,6 @@ must be present. =head1 BUGS -The way DNs are printed is in a "historical SSLeay" format which doesn't -follow any published standard. It should follow some standard like RFC2253 -or RFC1779 with options to make the stuff more readable. - Extensions in certificates are not transferred to certificate requests and vice versa. @@ -532,7 +694,7 @@ There should be options to explicitly set such things as start and end dates rather than an offset from the current time. The code to implement the verify behaviour described in the B<TRUST SETTINGS> -is currently being developed. It thus describes the intended behavior rather +is currently being developed. It thus describes the intended behaviour rather than the current behaviour. It is hoped that it will represent reality in OpenSSL 0.9.5 and later. |
