From: Dr. Stephen Henson Date: Fri, 21 Jan 2000 02:17:04 +0000 (+0000) Subject: Change the 'man' directory to 'apps'. Yes I wish cvs X-Git-Tag: OpenSSL_0_9_5beta1~237 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=dd46d58f65bd3a342bbcd8586680942be643fc7d;p=oweals%2Fopenssl.git Change the 'man' directory to 'apps'. Yes I wish cvs could rename too :-( --- diff --git a/doc/apps/asn1parse.pod b/doc/apps/asn1parse.pod new file mode 100644 index 0000000000..e76e9813ab --- /dev/null +++ b/doc/apps/asn1parse.pod @@ -0,0 +1,129 @@ +=pod + +=head1 NAME + +asn1parse - ASN.1 parsing tool + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-offset number>] +[B<-length number>] +[B<-i>] +[B<-oid filename>] +[B<-strparse offset>] + +=head1 DESCRIPTION + +The B command is a diagnostic utility that can parse ASN.1 +structures. It can also be used to extract data from ASN.1 formatted data. + +=head1 OPTIONS + +=over 4 + +=item B<-inform> B + +the input format. B is binary format and B (the default) is base64 +encoded. + +=item B<-in filename> + +the input file, default is standard input + +=item B<-out filename> + +output file to place the DER encoded data into. If this +option is not present then no data will be output. This is most useful when +combined with the B<-strparse> option. + +=item B<-noout> + +don't output the parsed version of the input file. + +=item B<-offset number> + +starting offset to begin parsing, default is start of file. + +=item B<-length number> + +number of bytes to parse, default is until end of file. + +=item B<-i> + +indents the output according to the "depth" of the structures. + +=item B<-oid filename> + +a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this +file is described in the NOTES section below. + +=item B<-strparse offset> + +parse the contents octets of the ASN.1 object starting at B. This +option can be used multiple times to "drill down" into a nested structure. + + +=back + +=head2 OUTPUT + +The output will typically contain lines like this: + + 0:d=0 hl=4 l= 681 cons: SEQUENCE + +..... + + 229:d=3 hl=3 l= 141 prim: BIT STRING + 373:d=2 hl=3 l= 162 cons: cont [ 3 ] + 376:d=3 hl=3 l= 159 cons: SEQUENCE + 379:d=4 hl=2 l= 29 cons: SEQUENCE + 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier + 386:d=5 hl=2 l= 22 prim: OCTET STRING + 410:d=4 hl=2 l= 112 cons: SEQUENCE + 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier + 417:d=5 hl=2 l= 105 prim: OCTET STRING + 524:d=4 hl=2 l= 12 cons: SEQUENCE + +..... + +This example is part of a self signed certificate. Each line starts with the +offset in decimal. B specifies the current depth. The depth is increased +within the scope of any SET or SEQUENCE. B gives the header length +(tag and length octets) of the current type. B gives the length of +the contents octets. + +The B<-i> option can be used to make the output more readable. + +Some knowledge of the ASN.1 structure is needed to interpret the output. + +In this example the BIT STRING at offset 229 is the certificate public key. +The contents octets of this will contain the public key information. This can +be examined using the option B<-strparse 229> to yield: + + 0:d=0 hl=3 l= 137 cons: SEQUENCE + 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897 + 135:d=1 hl=2 l= 3 prim: INTEGER :010001 + +=head1 NOTES + +If an OID is not part of OpenSSL's internal table it will be represented in +numerical form (for example 1.2.3.4). The file passed to the B<-oid> option +allows additional OIDs to be included. Each line consists of three columns, +the first column is the OID in numerical format and should be followed by white +space. The second column is the "short name" which is a single word followed +by white space. The final column is the rest of the line and is the +"long name". B displays the long name. Example: + +C<1.2.3.4 shortName A long name> + +=head1 BUGS + +There should be options to change the format of input lines. The output of some +ASN.1 types is not well handled (if at all). + +=cut diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod new file mode 100644 index 0000000000..999622b570 --- /dev/null +++ b/doc/apps/ca.pod @@ -0,0 +1,472 @@ + +=pod + +=head1 NAME + +ca - sample minimal CA application + +=head1 SYNOPSIS + +B B +[B<-verbose>] +[B<-config filename>] +[B<-name section>] +[B<-gencrl>] +[B<-revoke file>] +[B<-crldays days>] +[B<-crlhours hours>] +[B<-crlexts section>] +[B<-startdate date>] +[B<-enddate date>] +[B<-days arg>] +[B<-md arg>] +[B<-policy arg>] +[B<-keyfile arg>] +[B<-key arg>] +[B<-cert file>] +[B<-in file>] +[B<-out file>] +[B<-outdir dir>] +[B<-infiles>] +[B<-spkac file>] +[B<-ss_cert file>] +[B<-preserveDN>] +[B<-batch>] +[B<-msie_hack>] +[B<-extensions section>] + +=head1 DESCRIPTION + +The B command is a minimal CA application. It can be used +to sign certificate requests in a variety of forms and generate +CRLs it also maintains a text database of issued certificates +and their status. + +The options descriptions will be divided into each purpose. + +=head1 CA OPTIONS + +=over 4 + +=item B<-config filename> + +specifies the configuration file to use. + +=item B<-in filename> + +an input filename containing a single certificate request to be +signed by the CA. + +=item B<-ss_cert filename> + +a single self signed certificate to be signed by the CA. + +=item B<-spkac filename> + +a file containing a single Netscape signed public key and challenge +and additional field values to be signed by the CA. See the B +section for information on the required format. + +=item B<-infiles> + +if present this should be the last option, all subsequent arguments +are assumed to the the names of files containing certificate requests. + +=item B<-out filename> + +the output file to output certificates to. The default is standard +output. The certificate details will also be printed out to this +file. + +=item B<-outdir directory> + +the directory to output certificates to. The certificate will be +written to a filename consisting of the serial number in hex with +".pem" appended. + +=item B<-cert> + +the CA certificate file. + +=item B<-keyfile filename> + +the private key to sign requests with. + +=item B<-key password> + +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<-verbose> + +this prints extra details about the operations being performed. + +=item B<-startdate date> + +this allows the start date to be explicitly set. The format of the +date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). + +=item B<-enddate date> + +this allows the expiry date to be explicitly set. The format of the +date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). + +=item B<-days arg> + +the number of days to certify the certificate for. + +=item B<-md alg> + +the message digest to use. Possible values include md5, sha1 and mdc2. +This option also applies to CRLs. + +=item B<-policy arg> + +this option defines the CA "policy" to use. This is a section in +the configuration file which decides which fields should be mandatory +or match the CA certificate. Check out the B section +for more information. + +=item B<-msie_hack> + +this is a legacy option to make B work with very old versions of +the IE certificate enrollment control "certenr3". It used UniversalStrings +for almost everything. Since the old control has various security bugs +its use is strongly discouraged. The newer control "Xenroll" does not +need this option. + +=item B<-preserveDN> + +Normally the DN order of a certificate is the same as the order of the +fields in the relevant policy section. When this option is set the order +is the same as the request. This is largely for compatibility with the +older IE enrollment control which would only accept certificates if their +DNs match the order of the request. This is not needed for Xenroll. + +=item B<-batch> + +this sets the batch mode. In this mode no questions will be asked +and all certificates will be certified automatically. + +=item B<-extensions section> + +the section of the configuration file containing certificate extensions +to be added when a certificate is issued. 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. + +=back + +=head1 CRL OPTIONS + +=over 4 + +=item B<-gencrl> + +this option generates a CRL based on information in the index file. + +=item B<-crldays num> + +the number of days before the next CRL is due. That is the days from +now to place in the CRL nextUpdate field. + +=item B<-crlhours num> + +the number of hours before the next CRL is due. + +=item B<-revoke filename> + +a filename containing a certificate to revoke. + +=item B<-crlexts section> + +the section of the configuration file containing CRL extensions to +include. If no CRL extension section is present then a V1 CRL is +created, if the CRL extension section is present (even if it is +empty) then a V2 CRL is created. The CRL extensions specified are +CRL extensions and B CRL entry extensions. It should be noted +that some software (for example Netscape) can't handle V2 CRLs. + +=back + +=head1 CONFIGURATION FILE OPTIONS + +The options for B are contained in the B section of the +configuration file. Many of these are identical to command line +options. Where the option is present in the configuration file +and the command line the command line value is used. Where an +option is described as mandatory then it must be present in +the configuration file or the command line equivalent (if +any) used. + +=over 4 + +=item B + +This specifies a file containing additional B. +Each line of the file should consist of the numerical form of the +object identifier followed by white space then the short name followed +by white space and finally the long name. + +=item B + +This specifies a section in the configuration file containing extra +object identifiers. Each line should consist of the short name of the +object identifier followed by B<=> and the numerical form. The short +and long names are the same when this option is used. + +=item B + +the same as the B<-outdir> command line option. It specifies +the directory where new certificates will be placed. Mandatory. + +=item B + +the same as B<-cert>. It gives the file containing the CA +certificate. Mandatory. + +=item B + +same as the B<-keyfile> option. The file containing the +CA private key. Mandatory. + +=item B + +a file used to read and write random number seed information. + +=item B + +the same as the B<-days> option. The number of days to certify +a certificate for. + +=item B + +the same as the B<-startdate> option. The start date to certify +a certificate for. If not set the current time is used. + +=item B + +the same as the B<-enddate> option. Either this option or +B (or the command line equivalents) must be +present. + +=item B + +the same as the B<-crlhours> and the B<-crldays> options. These +will only be used if neither command line option is present. At +least one of these must be present to generate a CRL. + +=item B + +the same as the B<-md> option. The message digest to use. Mandatory. + +=item B + +the text database file to use. Mandatory. This file must be present +though initially it will be empty. + +=item B + +a text file containing the next serial number to use in hex. Mandatory. +This file must be present and contain a valid serial number. + +=item B + +the same as B<-extensions>. + +=item B + +the same as B<-crlexts>. + +=item B + +the same as B<-preserveDN> + +=item B + +the same as B<-msie_hack> + +=item B + +the same as B<-policy>. Mandatory. See the B section +for more information. + +=back + +=head1 POLICY FORMAT + +The policy section consists of a set of variables corresponding to +certificate DN fields. If the value is "match" then the field value +must match the same field in the CA certificate. If the value is +"supplied" then it must be present. If the value is "optional" then +it may be present. Any fields not mentioned in the policy section +are silently deleted, unless the B<-preserveDN> option is set but +this can be regarded more of a quirk than intended behaviour. + +=head1 SPKAC FORMAT + +The input to the B<-spkac> command line option is a Netscape +signed public key and challenge. This will usually come from +the B tag in an HTML form to create a new private key. +It is however possible to create SPKACs using the B utility. + +The file should contain the variable SPKAC set to the value of +the SPKAC and also the required DN components as name value pairs. +If you need to include the same component twice then it can be +preceded by a number and a '.'. + +=head1 EXAMPLES + +Note: these examples assume that the B directory structure is +already set up and the relevant files already exist. This usually +involves creating a CA certificate and private key with B, a +serial number file and an empty index file and placing them in +the relevant directories. + +To use the sample configuration file below the directories demoCA, +demoCA/private and demoCA/newcerts would be created. The CA +certificate would be copied to demoCA/cacert.pem and its private +key to demoCA/private/cakey.pem. A file demoCA/serial would be +created containing for example "01" and the empty index file +demoCA/index.txt. + + +Sign a certificate request: + +openssl ca -in req.pem -out newcert.pem + +Generate a CRL + +openssl ca -gencrl -out crl.pem + +Sign several requests: + +openssl ca -infiles req1.pem req2.pem req3.pem + +Certify a Netscape SPKAC: + +openssl ca -spkac spkac.txt + +A sample SPKAC file (the SPKAC line has been truncated for clarity): + + SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 + CN=Steve Test + emailAddress=steve@openssl.org + 0.OU=OpenSSL Group + 1.OU=Another Group + +A sample configuration file with the relevant sections for B: + + [ ca ] + default_ca = CA_default # The default ca section + + [ CA_default ] + + dir = ./demoCA # top dir + database = $dir/index.txt # index file. + new_certs_dir = $dir/newcerts # new certs dir + + certificate = $dir/cacert.pem # The CA cert + serial = $dir/serial # serial no file + private_key = $dir/private/cakey.pem# CA private key + RANDFILE = $dir/private/.rand # random number file + + default_days = 365 # how long to certify for + default_crl_days= 30 # how long before next CRL + default_md = md5 # md to use + + policy = policy_any # default policy + + [ policy_any ] + countryName = supplied + stateOrProvinceName = optional + organizationName = optional + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + +=head1 WARNINGS + +The B command is quirky and at times downright unfriendly. + +The B utility was originally meant as an example of how to do things +in a CA. It was not supposed be be used as a full blown CA itself: +nevertheless some people are using it for this purpose. + +The B command is effectively a single user command: no locking is +done on the various files and attempts to run more than one B command +on the same database can have unpredictable results. + +=head1 FILES + +Note: the location of all files can change either by compile time options, +configuration file entries, environment variables or command line options. +The values below reflect the default values. + + /usr/local/ssl/lib/openssl.cnf - master configuration file + ./demoCA - main CA directory + ./demoCA/cacert.pem - CA certificate + ./demoCA/private/cakey.pem - CA private key + ./demoCA/serial - CA serial number file + ./demoCA/serial.old - CA serial number backup file + ./demoCA/index.txt - CA text database file + ./demoCA/index.txt.old - CA text database backup file + ./demoCA/certs - certificate output file + ./demoCA/.rnd - CA random seed information + +=head1 ENVIRONMENT VARIABLES + +B reflects the location of master configuration file it can +be overridden by the B<-config> command line option. + +=head1 RESTRICTIONS + +The text database index file is a critical part of the process and +if corrupted it can be difficult to fix. It is theoretically possible +to rebuild the index file from all the issued certificates and a current +CRL: however there is no option to do this. + +CRL entry extensions cannot currently be created: only CRL extensions +can be added. + +V2 CRL features like delta CRL support and CRL numbers are not currently +supported. + +Although several requests can be input and handled at once it is only +possible to include one SPKAC or self signed certificate. + +=head1 BUGS + +The use of an in memory text database can cause problems when large +numbers of certificates are present because, as the name implies +the database has to be kept in memory. + +Certificate request extensions are ignored: some kind of "policy" should +be included to use certain static extensions and certain extensions +from the request. + +It is not possible to certify two certificates with the same DN: this +is a side effect of how the text database is indexed and it cannot easily +be fixed without introducing other problems. Some S/MIME clients can use +two certificates with the same DN for separate signing and encryption +keys. + +The B command really needs rewriting or the required functionality +exposed at either a command or interface level so a more friendly utility +(perl script or GUI) can handle things properly. The scripts B and +B help a little but not very much. + +Any fields in a request that are not present in a policy are silently +deleted. This does not happen if the B<-preserveDN> option is used but +the extra fields are not displayed when the user is asked to certify +a request. The behaviour should be more friendly and configurable. + +Cancelling some commands by refusing to certify a certificate can +create an empty file. + +=head1 SEE ALSO + +req(1), spkac(1), x509(1), CA.pl(1), config(5) + +=cut diff --git a/doc/apps/config.pod b/doc/apps/config.pod new file mode 100644 index 0000000000..a5974d945a --- /dev/null +++ b/doc/apps/config.pod @@ -0,0 +1,138 @@ + +=pod + +=head1 NAME + +config - OpenSSL CONF library configuration files + +=head1 DESCRIPTION + +The OpenSSL CONF library can be used to read configuration files. +It is used for the OpenSSL master configuration file B +and in a few other places like B files and certificate extension +files for the B utility. + +A configuration file is divided into a number of sections. Each section +starts with a line B<[ section_name ]> and ends when a new section is +started or end of file is reached. A section name can consist of +alphanumeric characters and underscores. + +The first section of a configuration file is special and is referred +to as the B section this is usually unnamed and is from the +start of file until the first named section. When a name is being looked up +it is first looked up in a named section (if any) and then the +default section. + +The environment is mapped onto a section called B. + +Comments can be included by preceding them with the B<#> character + +Each section in a configuration file consists of a number of name and +value pairs of the form B + +The B string can contain any alphanumeric characters as well as +a few punctuation symbols such as B<.> B<,> B<;> and B<_>. + +The B string consists of the string following the B<=> character +until end of line with any leading and trailing white space removed. + +The value string undergoes variable expansion. This can be done by +including the form B<$var> or B<${var}>: this will substitute the value +of the named variable in the current section. It is also possible to +substitute a value from another section using the syntax B<$section::name> +or B<${section::name}>. By using the form B<$ENV::name> environment +variables can be substituted. It is also possible to assign values to +environment variables by using the name B, this will work +if the program looks up environment variables using the B library +instead of calling B directly. + +It is possible to escape certain characters by using any kind of quote +or the B<\> character. By making the last character of a line a B<\> +a B string can be spread across multiple lines. In addition +the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognised. + +=head1 NOTES + +If a configuration file attempts to expand a variable that doesn't exist +then an error is flagged and the file will not load. This can happen +if an attempt is made to expand an environment variable that doesn't +exist. For example the default OpenSSL master configuration file used +the value of B which may not be defined on non Unix systems. + +This can be worked around by including a B section to provide +a default value: then if the environment lookup fails the default value +will be used instead. For this to work properly the default value must +be defined earlier in the configuration file than the expansion. See +the B section for an example of how to do this. + +If the same variable exists in the same section then all but the last +value will be silently ignored. In certain circumstances such as with +DNs the same field may occur multiple times. This is usually worked +around by ignoring any characters before an initial B<.> e.g. + + 1.OU="My first OU" + 2.OU="My Second OU" + +=head1 EXAMPLES + +Here is a sample configuration file using some of the features +mentioned above. + + # This is the default section. + + HOME=/temp + RANDFILE= ${ENV::HOME}/.rnd + configdir=$ENV::HOME/config + + [ section_one ] + + # We are now in section one. + + # Quotes permit leading and trailing whitespace + any = " any variable name " + + other = A string that can \ + cover several lines \ + by including \\ characters + + message = Hello World\n + + [ section_two ] + + greeting = $section_one::message + +This next example shows how to expand environment variables safely. + +Suppose you want a variable called B to refer to a +temporary filename. The directory it is placed in can determined by +the the B or B environment variables but they may not be +set to any value at all. If you just include the environment variable +names and the variable doesn't exist then this will cause an error when +an attempt is made to load the configuration file. By making use of the +default section both values can be looked up with B taking +priority and B used if neither is defined: + + TMP=/tmp + # The above value is used if TMP isn't in the environment + TEMP=$ENV::TMP + # The above value is used if TEMP isn't in the environment + tmpfile=${ENV::TEMP}/tmp.filename + +=head1 BUGS + +Currently there is no way to include characters using the octal B<\nnn> +form. Strings are all null terminated so nulls cannot form part of +the value. + +The escaping isn't quite right: if you want to use sequences like B<\n> +you can't use any quote escaping on the same line. + +Files are loaded in a single pass. This means that an variable expansion +will only work if the variables referenced are defined earlier in the +file. + +=head1 SEE ALSO + +x509(1), req(1), ca(1) + +=cut diff --git a/doc/apps/crl.pod b/doc/apps/crl.pod new file mode 100644 index 0000000000..8b19592c85 --- /dev/null +++ b/doc/apps/crl.pod @@ -0,0 +1,110 @@ +=pod + +=head1 NAME + +crl - CRL utility + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-text>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-hash>] +[B<-issuer>] +[B<-lastupdate>] +[B<-nextupdate>] +[B<-CAfile file>] +[B<-CApath dir>] + +=head1 DESCRIPTION + +The B command processes CRL files in DER or PEM format. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format. B format is DER encoded CRL +structure. B (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=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 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<-text> + +print out the CRL in text form. + +=item B<-noout> + +don't output the encoded version of the CRL. + +=item B<-hash> + +output a hash of the issuer name. This can be use to lookup CRLs in +a directory by issuer name. + +=item B<-issuer> + +output the issuer name. + +=item B<-lastupdate> + +output the lastUpdate field. + +=item B<-nextupdate> + +output the nextUpdate field. + +=item B<-CAfile file> + +verify the signature on a CRL by looking up the issuing certificate in +B + +=item B<-CApath dir> + +verify the signature on a CRL by looking up the issuing certificate in +B. This directory must be a standard certificate directory: that +is a hash of each subject name (using B) should be linked +to each certificate. + +=back + +=head1 EXAMPLES + +Convert a CRL file from PEM to DER: + + openssl crl -in crl.pem -outform DER -out crl.der + +Output the text form of a DER encoded certificate: + + openssl crl -in crl.der -text -noout + +=head1 BUGS + +Ideally it should be possible to create a CRL using appropriate options +and files too. + +=head1 SEE ALSO + +crl2pkcs7(1), ca(1), x509(1) + +=cut diff --git a/doc/apps/crl2pkcs7.pod b/doc/apps/crl2pkcs7.pod new file mode 100644 index 0000000000..ad749ed0c3 --- /dev/null +++ b/doc/apps/crl2pkcs7.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates. + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-print_certs>] + +=head1 DESCRIPTION + +The B command takes an optional CRL and one or more +certificates and converts them into a PKCS#7 degenerate "certificates +only" structure. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the CRL input format. B format is DER encoded CRL +structure.B (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the PKCS#7 structure output format. B format is DER +encoded PKCS#7 structure.B (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-in filename> + +This specifies the input filename to read a CRL from or standard input if this +option is not specified. + +=item B<-out filename> + +specifies the output filename to write the PKCS#7 structure to or standard +output by default. + +=item B<-certfile filename> + +specifies a filename containing one or more certificates in B format. +All certificates in the file will be added to the PKCS#7 structure. This +option can be used more than once to read certificates form multiple +files. + +=item B<-nocrl> + +normally a CRL is included in the output file. With this option no CRL is +included in the output file and a CRL is not read from the input file. + +=back + +=head1 EXAMPLES + +Create a PKCS#7 structure from a certificate and CRL: + + openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem + +Creates a PKCS#7 structure in DER format with no CRL from several +different certificates: + + openssl crl2pkcs7 -nocrl -certfile newcert.pem + -certfile demoCA/cacert.pem -outform DER -out p7.der + +=head1 NOTES + +The output file is a PKCS#7 signed data structure containing no signers and +just certificates and an optional CRL. + +This utility can be used to send certificates and CAs to Netscape as part of +the certificate enrollment process. This involves sending the DER encoded output +as MIME type application/x-x509-user-cert. + +The B encoded form with the header and footer lines removed can be used to +install user certificates and CAs in MSIE using the Xenroll control. + +=head1 SEE ALSO + +pkcs7(1) + +=cut diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod new file mode 100644 index 0000000000..cbf2cc529a --- /dev/null +++ b/doc/apps/dgst.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +dgst, md5, md2, sha1, sha, mdc2, ripemd160 - message digests + +=head1 SYNOPSIS + +[B] +[B<-md5|-md2|-sha1|-sha|mdc2|-ripemd160>] +[B<-c>] +[B<-d>] +[B] + +[B] +[B<-c>] +[B<-d>] +[B] + +=head1 DESCRIPTION + +The digest functions print out the message digest of a supplied file or files +in hexadecimal form. + +=head1 OPTIONS + +=over 4 + +=item B<-c> + +print out the digest in two digit groups separated by colons. + +=item B<-d> + +print out BIO debugging information. + +=item B + +file or files to digest. If no files are specified then standard input is +used. + +=back + +=head1 NOTES + +The digest of choice for all new applications is SHA1. Other digests are +however still widely used. + +=cut diff --git a/doc/apps/dh.pod b/doc/apps/dh.pod new file mode 100644 index 0000000000..99b307368f --- /dev/null +++ b/doc/apps/dh.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +dh - DH parameter manipulation and generation + +=head1 SYNOPSIS + +B +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-text>] +[B<-C>] + +=head1 DESCRIPTION + +This command is used to manipulate DH parameter files. + +=head1 OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format. The B option uses an ASN1 DER encoded +form compatible with the PKCS#3 DHparameter structure. The PEM form is the +default format: it consists of the B format base64 encoded with +additional header and footer lines. + +=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 parameters from or standard input if +this option is not specified. + +=item B<-out filename> + +This specifies the output filename parameters to. Standard output is used +if this option is not present. The output filename should B be the same +as the input filename. + +=item B<-noout> + +this option inhibits the output of the encoded version of the parameters. + +=item B<-text> + +this option prints out the DH parameters in human readable form. + +=item B<-C> + +this option converts the parameters into C code. The parameters can then +be loaded by calling the B function. + +=back + +=head1 NOTES + +PEM format DH parameters use the header and footer lines: + + -----BEGIN DH PARAMETERS----- + -----END DH PARAMETERS----- + +OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42 +DH. + +This program manipulates DH parameters not keys. + +=head1 BUGS + +This program is badly named: the B and B programs manipulate keys +and not parameters. + +There should be a way to generate and manipulate DH keys. + +=head1 SEE ALSO + +dsaparam(1) + +=cut diff --git a/doc/apps/dsa.pod b/doc/apps/dsa.pod new file mode 100644 index 0000000000..1235e5598b --- /dev/null +++ b/doc/apps/dsa.pod @@ -0,0 +1,154 @@ +=pod + +=head1 NAME + +dsa - DSA key processing + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin password>] +[B<-envpassin var>] +[B<-out filename>] +[B<-passout password>] +[B<-envpassout var>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-text>] +[B<-noout>] +[B<-modulus>] +[B<-pubin>] +[B<-pubout>] + +=head1 DESCRIPTION + +The B command processes DSA keys. They can be converted between various +forms and their components printed out. B This command uses the +traditional SSLeay compatible format for private key encryption: newer +applications should use the more secure PKCS#8 format using the B + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format. The B option with a private key uses +an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of +version (currently zero), p, q, g, the public and private key components +respectively as ASN.1 INTEGERs. When used with a public key it uses a +SubjectPublicKeyInfo structure: it is an error if the key is not DSA. + +The B form is the default format: it consists of the B format base64 +encoded with additional header and footer lines. In the case of a private key +PKCS#8 format is also accepted. + +=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 password> + +the input file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassin var> + +read the input file password from the environment variable B. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output by +is not specified. If any encryption options are set then a pass phrase will be +prompted for. The output filename should B be the same as the input +filename. + +=item B<-passout password> + +the output file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassout var> + +read the output file password from the environment variable B. + +=item B<-des|-des3|-idea> + +These options encrypt the private key with the DES, triple DES, or the +IDEA ciphers respectively before outputting it. A pass phrase is prompted for. +If none of these options is specified the key is written in plain text. This +means that using the B utility to read in an encrypted key with no +encryption option can be used to remove the pass phrase from a key, or by +setting the encryption options it can be use to add or change the pass phrase. +These options can only be used with PEM format output files. + +=item B<-text> + +prints out the public, private key components and parameters. + +=item B<-noout> + +this option prevents output of the encoded version of the key. + +=item B<-modulus> + +this option prints out the value of the public key component of the key. + +=item B<-pubin> + +by default a private key is input file with this option a public key is input +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. + +=back + +=head1 NOTES + +The PEM private key format uses the header and footer lines: + + -----BEGIN DSA PRIVATE KEY----- + -----END DSA PRIVATE KEY----- + +=head1 EXAMPLES + +To remove the pass phrase on a DSA private key: + +C + +To encrypt a private key using triple DES: + +C + +To convert a private key from PEM to DER format: + +C + +To print out the components of a private key to standard output: + +C + +To just output the public part of a private key: + +C + +=head1 SEE ALSO + +dsaparam(1), gendsa(1), rsa(1), genrsa(1) + +=cut diff --git a/doc/apps/dsaparam.pod b/doc/apps/dsaparam.pod new file mode 100644 index 0000000000..f5f3f317bd --- /dev/null +++ b/doc/apps/dsaparam.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +dsaparam - DSA parameter manipulation and generation + +=head1 SYNOPSIS + +B +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-text>] +[B<-C>] +[B<-rand file(s)>] +[B<-genkey>] +[B] + +=head1 DESCRIPTION + +This command is used to manipulate or generate DSA parameter files. + +=head1 OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format. The B option uses an ASN1 DER encoded +form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting +of p, q and g respectively. The PEM form is the default format: it consists +of the B format base64 encoded with additional header and footer lines. + +=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 parameters from or standard input if +this option is not specified. If the B parameter is included then +this option will be ignored. + +=item B<-out filename> + +This specifies the output filename parameters to. Standard output is used +if this option is not present. The output filename should B be the same +as the input filename. + +=item B<-noout> + +this option inhibits the output of the encoded version of the parameters. + +=item B<-text> + +this option prints out the DSA parameters in human readable form. + +=item B<-C> + +this option converts the parameters into C code. The parameters can then +be loaded by calling the B function. + +=item B<-genkey> + +this option will generate a DSA either using the specified or generated +parameters. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator. Multiple files can be specified separated by a OS-dependent +character. For MS-Windows, the separator is B<;>. For OpenVMS, it's +B<,>. For all others, it's B<:>. + +=item B + +this option specifies that a parameter set should be generated of size +B. It must be the last option. If this option is included then +the input file (if any) is ignored. + +=back + +=head1 NOTES + +PEM format DSA parameters use the header and footer lines: + + -----BEGIN DSA PARAMETERS----- + -----END DSA PARAMETERS----- + +DSA parameter generation is a slow process and as a result the same set of +DSA parameters is often used to generate several distinct keys. + +=head1 SEE ALSO + +gendsa(1), dsa(1), genrsa(1), rsa(1) + +=cut diff --git a/doc/apps/enc.pod b/doc/apps/enc.pod new file mode 100644 index 0000000000..349fca00f8 --- /dev/null +++ b/doc/apps/enc.pod @@ -0,0 +1,248 @@ +=pod + +=head1 NAME + +enc - symmetric cipher routines + +=head1 SYNOPSIS + +B +[B<-in filename>] +[B<-out filename>] +[B<-e>] +[B<-d>] +[B<-a>] +[B<-A>] +[B<-k password>] +[B<-kfile filename>] +[B<-K key>] +[B<-iv IV>] +[B<-p>] +[B<-P>] +[B<-bufsize number>] +[B<-debug>] + +=head1 DESCRIPTION + +The symmetric cipher commands allow data to be encrypted or decrypted +using various block and stream ciphers using keys based on passwords +or explicitly provided. Base64 encoding or decoding can also be performed +either by itself or in addition to the encryption or decryption. + +=head1 OPTIONS + +=over 4 + +=item B<-in filename> + +the input filename, standard input by default. + +=item B<-out filename> + +the output filename, standard output by default. + +=item B<-salt> + +use a salt in the key derivation routines. This option should B +be used unless compatibility with previous versions of OpenSSL or SSLeay +is required. This option is only present on OpenSSL versions 0.9.5 or +above. + +=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. + +=item B<-e> + +encrypt the input data: this is the default. + +=item B<-d> + +decrypt the input data. + +=item B<-a> + +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<-A> + +if the B<-a> option is set then base64 process the data on one line. + +=item B<-k password> + +the password to derive the key from. + +=item B<-kfile filename> + +read the password to derive the key from the first line of B + +=item B<-S salt> + +the actual salt to use: this must be represented as a string comprised only +of hex digits. + +=item B<-K key> + +the actual key to use: this must be represented as a string comprised only +of hex digits. + +=item B<-iv IV> + +the actual IV to use: this must be represented as a string comprised only +of hex digits. + +=item B<-p> + +print out the key and IV used. + +=item B<-P> + +print out the key and IV used then immediately exit: don't do any encryption +or decryption. + +=item B<-bufsize number> + +set the buffer size for I/O + +=item B<-debug> + +debug the BIOs used for I/O. + +=back + +=head1 NOTES + +The program can be called either as B or +B. + +A password will be prompted for to derive the key and IV if necessary. + +The B<-salt> option should B be used if the key is being derived +from a password unless you want compatibility with previous versions of +OpenSSL and SSLeay. + +Without the B<-salt> option it is possible to perform efficient dictionary +attacks on the password and to attack stream cipher encrypted data. The reason +for this is that without the salt the same password always generates the same +encryption key. When the salt is being used the first eight bytes of the +encrypted data are reserved for the salt: it is generated at random when +encrypting a file and read from the encrypted file when it is decrypted. + +Some of the ciphers do not have large keys and others have security +implications if not used correctly. A beginner is advised to just use +a strong block cipher in CBC mode such as bf or des3. + +All the block ciphers use PKCS#5 padding also known as standard block +padding: this allows a rudimentary integrity or password check to be +performed. However since the chance of random data passing the test is +better than 1 in 256 it isn't a very good test. + +All RC2 ciphers have the same key and effective key length. + +Blowfish and RC5 algorithms use a 128 bit key. + +=head1 SUPPORTED CIPHERS + + base64 Base 64 + + bf-cbc Blowfish in CBC mode + bf Alias for bf-cbc + bf-cfb Blowfish in CFB mode + bf-ecb Blowfish in ECB mode + bf-ofb Blowfish in OFB mode + + cast-cbc CAST in CBC mode + cast Alias for cast-cbc + cast5-cbc CAST5 in CBC mode + cast5-cfb CAST5 in CFB mode + cast5-ecb CAST5 in ECB mode + cast5-ofb CAST5 in OFB mode + + des-cbc DES in CBC mode + des Alias for des-cbc + des-cfb DES in CBC mode + des-ofb DES in OFB mode + des-ecb DES in ECB mode + + des-ede-cbc Two key triple DES EDE in CBC mode + des-ede Alias for des-ede + des-ede-cfb Two key triple DES EDE in CFB mode + des-ede-ofb Two key triple DES EDE in OFB mode + + des-ede3-cbc Three key triple DES EDE in CBC mode + des-ede3 Alias for des-ede3-cbc + des3 Alias for des-ede3-cbc + des-ede3-cfb Three key triple DES EDE CFB mode + des-ede3-ofb Three key triple DES EDE in OFB mode + + desx DESX algorithm. + + idea-cbc IDEA algorithm in CBC mode + idea same as idea-cbc + idea-cfb IDEA in CFB mode + idea-ecb IDEA in ECB mode + idea-ofb IDEA in OFB mode + + rc2-cbc 128 bit RC2 in CBC mode + rc2 Alias for rc2-cbc + rc2-cfb 128 bit RC2 in CBC mode + rc2-ecb 128 bit RC2 in CBC mode + rc2-ofb 128 bit RC2 in CBC mode + rc2-64-cbc 64 bit RC2 in CBC mode + rc2-40-cbc 40 bit RC2 in CBC mode + + rc4 128 bit RC4 + rc4-64 64 bit RC4 + rc4-40 40 bit RC4 + + rc5-cbc RC5 cipher in CBC mode + rc5 Alias for rc5-cbc + rc5-cfb RC5 cipher in CBC mode + rc5-ecb RC5 cipher in CBC mode + rc5-ofb RC5 cipher in CBC mode + +=head1 EXAMPLES + +Just base64 encode a binary file: + + openssl base64 -in file.bin -out file.b64 + +Decode the same file + + openssl base64 -d -in file.b64 -out file.bin + +Encrypt a file using triple DES in CBC mode using a prompted password: + + openssl des3 -salt -in file.txt -out file.des3 + +Decrypt a file using a supplied password: + + openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword + +Encrypt a file then base64 encode it (so it can be sent via mail for example) +using Blowfish in CBC mode: + + openssl bf -a -salt -in file.txt -out file.bf + +Base64 decode a file then decrypt it: + + openssl bf -d -salt -a -in file.bf -out file.txt + +Decrypt some data using a supplied 40 bit RC4 key: + + openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 + +=head1 BUGS + +The B<-A> option when used with large files doesn't work properly. + +There should be an option to allow an iteration count to be included. + +Like the EVP library the B program only supports a fixed number of +algorithms with certain parameters. So if, for example, you want to use RC2 +with a 76 bit key or RC4 with an 84 bit key you can't use this program. + +=cut diff --git a/doc/apps/gendh.pod b/doc/apps/gendh.pod new file mode 100644 index 0000000000..8262622a3d --- /dev/null +++ b/doc/apps/gendh.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +gendh - DH parameter generation + +=head1 SYNOPSIS + +B +[B<-out filename>] +[B<-2>] +[B<-5>] +[B<-rand file(s)>] +[numbits] + +=head1 DESCRIPTION + +This command is used to generate DH parameter files. + +=head1 OPTIONS + +=over 4 + +=item B<-out filename> + +This specifies the output filename parameters to. Standard output is used +if this option is not present. The output format is a base64 encoded form of +a PKCS#5 DHParameter structure. + +=item B<-2>, B<-5> + +The generator to use, either 2 or 5. 2 is the default. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator. Multiple files can be specified separated by a OS-dependent +character. For MS-Windows, the separator is B<;>. For OpenVMS, it's +B<,>. For all others, it's B<:>. + +=item B + +this option specifies that a parameter set should be generated of size +B. It must be the last option. If not present then a value of 512 +is used. + +=back + +=head1 NOTES + +PEM format DH parameters use the header and footer lines: + + -----BEGIN DH PARAMETERS----- + -----END DH PARAMETERS----- + +DH parameter generation is a slow process and as a result the same set of +DH parameters is often reused. + +OpenSSL currently uses PKCS#3 DH not the more recent X9.42 DH. + +This program creates DH parameters only, not DH keys. + +=head1 BUGS + +The program is badly named. The programs B and B generate +actual keys and not parameters. + +There should be a way to generate and manipulate DH keys. + +=head1 SEE ALSO + +dsaparam(1) + +=cut diff --git a/doc/apps/gendsa.pod b/doc/apps/gendsa.pod new file mode 100644 index 0000000000..a23e755fa8 --- /dev/null +++ b/doc/apps/gendsa.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +gendsa - generate a DSA private key from a set of parameters + +=head1 SYNOPSIS + +B B +[B<-out filename>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-rand file(s)>] +[B] + +=head1 DESCRIPTION + +The B command generates a DSA private key from a DSA parameter file +(which will be typically generated by the B command). + +=head1 OPTIONS + +=over 4 + +=item B<-des|-des3|-idea> + +These options encrypt the private key with the DES, triple DES, or the +IDEA ciphers respectively before outputting it. A pass phrase is prompted for. +If none of these options is specified no encryption is used. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator. Multiple files can be specified separated by a OS-dependent +character. For MS-Windows, the separator is B<;>. For OpenVMS, it's +B<,>. For all others, it's B<:>. + +=item B + +This option specifies the DSA parameter file to use. The parameters in this +file determine the size of the private key. DSA parameters can be generated +and examined using the B command. + +=back + +=head1 NOTES + +DSA key generation is little more than random number generation so it is +much quicker that RSA key generation for example. + +=head1 SEE ALSO + +dsaparam(1), dsa(1), genrsa(1), rsa(1) + +=cut diff --git a/doc/apps/genrsa.pod b/doc/apps/genrsa.pod new file mode 100644 index 0000000000..b224bd1fc8 --- /dev/null +++ b/doc/apps/genrsa.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +genrsa - generate an RSA private key + + +=head1 SYNOPSIS + +B B +[B<-out filename>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-f4>] +[B<-3>] +[B<-rand file(s)>] +[B] + +=head1 DESCRIPTION + +The B command generates an RSA private key. + +=head1 OPTIONS + +=over 4 + +=item B<-des|-des3|-idea> + +These options encrypt the private key with the DES, triple DES, or the +IDEA ciphers respectively before outputting it. A pass phrase is prompted for. +If none of these options is specified no encryption is used. + +=item B<-F4|-3> + +the public exponent to use, either 65537 or 3. The default is 65537. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator. Multiple files can be specified separated by a OS-dependent +character. For MS-Windows, the separator is B<;>. For OpenVMS, it's +B<,>. For all others, it's B<:>. + +=item B + +the size of the private key to generate in bits. This must be the last option +specified. The default is 512. + +=back + +=head1 NOTES + +RSA private key generation essentially involves the generation of two prime +numbers. When generating a private key various symbols will be output to +indicate the progress of the generation. A B<.> represents each number tested. +A B<+> means a number has passed a single primality test. A newline means that +the number has passed all the prime tests (currently set to 5 single tests). + +Because key generation is a random process the time taken to generate a key +may vary somewhat. + +=head1 BUGS + +A quirk of the prime generation algorithm is that it cannot generate small +primes. Therefore the number of bits should not be less that 64. For typical +private keys this will not matter because for security reasons they will +be much larger (typically 1024 bits). + +=head1 SEE ALSO + +gendsa(1) diff --git a/doc/apps/nseq.pod b/doc/apps/nseq.pod new file mode 100644 index 0000000000..989c3108fb --- /dev/null +++ b/doc/apps/nseq.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +nseq - create or examine a netscape certificate sequence + +=head1 SYNOPSIS + +B B +[B<-in filename>] +[B<-out filename>] +[B<-toseq>] + +=head1 DESCRIPTION + +The B command takes a file containing a Netscape certificate +sequence and prints out the certificates contained in it or takes a +file of certificates and converts it into a Netscape certificate +sequence. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies the input filename to read or standard input if this +option is not specified. + +=item B<-out filename> + +specifies the output filename or standard output by default. + +=item B<-toseq> + +normally a Netscape certificate sequence will be input and the output +is the certificates contained in it. With the B<-toseq> option the +situation is reversed: a Netscape certificate sequence is created from +a file of certificates. + +=back + +=head1 EXAMPLES + +Output the certificates in a Netscape certificate sequence + + openssl nseq -in nseq.pem -out certs.pem + +Create a Netscape certificate sequence + + openssl nseq -in certs.pem -toseq -out nseq.pem + +=head1 NOTES + +The B encoded form uses the same headers and footers as a certificate: + + -----BEGIN CERTIFICATE----- + -----END CERTIFICATE----- + +A Netscape certificate sequence is a Netscape specific form that can be sent +to browsers as an alternative to the standard PKCS#7 format when several +certificates are sent to the browser: for example during certificate enrollment. +It is used by Netscape certificate server for example. + +=head1 BUGS + +This program needs a few more options: like allowing DER or PEM input and +output files and allowing multiple certificate files to be used. + +=cut diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod new file mode 100644 index 0000000000..f5ce14ca2f --- /dev/null +++ b/doc/apps/openssl.pod @@ -0,0 +1,240 @@ + +=pod + +=head1 NAME + +openssl - OpenSSL command line tool + +=head1 SYNOPSIS + +B +I +[ I ] +[ I ] + +=head1 DESCRIPTION + +OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL +v2/v3) and Transport Layer Security (TLS v1) network protocols and related +cryptography standards required by them. + +The B program is a command line tool for using the various +cryptography functions of OpenSSL's B library from the shell. +It can be used for + + o Creation of RSA, DH and DSA key parameters + o Creation 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 + +=head1 COMMAND SUMMARY + +The B program provides a rich variety of commands (I in the +SYNOPSIS above), each of which often has a wealth of options and arguments +(I and I in the SYNOPSIS). + +=head2 STANDARD COMMANDS + +=over 10 + +=item B + +Parse an ASN.1 sequence. + +=item B + +Certificate Authority (CA) Management. + +=item B + +Cipher Suite Description Determination. + +=item B + +Certificate Revocation List (CRL) Management. + +=item B + +CRL to PKCS#7 Conversion. + +=item B + +Message Digest Calculation. + +=item B + +Diffie-Hellman Data Management. + +=item B + +DSA Data Management. + +=item B + +DSA Parameter Generation. + +=item B + +Encoding with Ciphers. + +=item B + +Error Number to Error String Conversion. + +=item B + +Generation of Diffie-Hellman Parameters. + +=item B + +Generation of DSA Parameters. + +=item B + +Generation of RSA Parameters. + +=item B + +PKCS#7 Data Management. + +=item B + +X.509 Certificate Signing Request (CSR) Management. + +=item B + +RSA Data Management. + +=item B + +This implements a generic SSL/TLS client which can establish a transparent +connection to a remote server speaking SSL/TLS. It's intended for testing +purposes only and provides only rudimentary interface functionality but +internally uses mostly all functionality of the OpenSSL B library. + +=item B + +This implements a generic SSL/TLS server which accepts connections from remote +clients speaking SSL/TLS. It's intended for testing purposes only and provides +only rudimentary interface functionality but internally uses mostly all +functionality of the OpenSSL B library. It provides both an own command +line oriented protocol for testing SSL functions and a simple HTTP response +facility to emulate an SSL/TLS-aware webserver. + +=item B + +SSL Connection Timer. + +=item B + +SSL Session Data Management. + +=item B + +Algorithm Speed Measurement. + +=item B + +X.509 Certificate Verification. + +=item B + +OpenSSL Version Information. + +=item B + +X.509 Certificate Data Management. + +=back + +=head2 MESSAGE DIGEST COMMANDS + +=over 10 + +=item B + +MD2 Digest + +=item B + +MD5 Digest + +=item B + +MDC2 Digest + +=item B + +RMD-160 Digest + +=item B + +SHA Digest + +=item B + +SHA-1 Digest + +=back + +=head2 ENCODING AND CIPHER COMMANDS + +=over 10 + +=item B + +Base64 Encoding + +=item B + +Blowfish Cipher + +=item B + +CAST Cipher + +=item B + +CAST5 Cipher + +=item B + +DES Cipher + +=item B + +Triple-DES Cipher + +=item B + +IDEA Cipher + +=item B + +RC2 Cipher + +=item B + +RC4 Cipher + +=item B + +RC5 Cipher + +=back + +=head1 SEE ALSO + +asn1parse(1), ca(1), config(1), crl(1), crl2pkcs7(1), dgst(1), dh(1), +dsa(1), dsaparam(1), enc(1), gendh(1), gendsa(1), genrsa(1), nseq(1), +openssl(1), pkcs12(1), pkcs7(1), pkcs8(1), req(1), rsa(1), s_client(1), +s_server(1), smime(1), spkac(1), verify(1), version(1), x509(1), +crypto(3), ssl(3) + +=head1 HISTORY + +The openssl(1) document appeared in OpenSSL 0.9.2 + +=cut + diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod new file mode 100644 index 0000000000..14982096c1 --- /dev/null +++ b/doc/apps/pkcs12.pod @@ -0,0 +1,286 @@ + +=pod + +=head1 NAME + +pkcs12 - PKCS#12 file utility + +=head1 SYNOPSIS + +B B +[B<-export>] +[B<-chain>] +[B<-inkey filename>] +[B<-certfile filename>] +[B<-name name>] +[B<-caname name>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-nomacver>] +[B<-nocerts>] +[B<-clcerts>] +[B<-cacerts>] +[B<-nokeys>] +[B<-info>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-nodes>] +[B<-noiter>] +[B<-maciter>] +[B<-twopass>] +[B<-descert>] +[B<-certpbe>] +[B<-keypbe>] +[B<-keyex>] +[B<-keysig>] +[B<-password password>] +[B<-envpass var>] + +=head1 DESCRIPTION + +The B command allows PKCS#12 files (sometimes referred to as +PFX files) to be created and parsed. PKCS#12 files are used by several +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 +file can be created by using the B<-export> option (see below). + +=head1 PARSING OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies filename of the PKCS#12 file to be parsed. Standard input is used +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. + +=item B<-pass password> + +the PKCS#12 file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpass var> + +read the PKCS#12 file password from the environment variable B. + +=item B<-noout> + +this option inhibits output of the keys and certificates to the output file version +of the PKCS#12 file. + +=item B<-clcerts> + +only output client certificates (not CA certificates). + +=item B<-cacerts> + +only output CA certificates (not client certificates). + +=item B<-nocerts> + +no certificates at all will be output. + +=item B<-nokeys> + +no private keys will be output. + +=item B<-info> + +output additional information about the PKCS#12 file structure, algorithms used and +iteration counts. + +=item B<-des> + +use DES to encrypt private keys before outputting. + +=item B<-des3> + +use triple DES to encrypt private keys before outputting, this is the default. + +=item B<-idea> + +use IDEA to encrypt private keys before outputting. + +=item B<-nodes> + +don't encrypt the private keys at all. + +=item B<-nomacver> + +don't attempt to verify the integrity MAC before reading the file. + +=item B<-twopass> + +prompt for separate integrity and encryption passwords: most software +always assumes these are the same so this option will render such +PKCS#12 files unreadable. + +=back + +=head1 FILE CREATION OPTIONS + +=over 4 + +=item B<-export> + +This option specifies that a PKCS#12 file will be created rather than +parsed. + +=item B<-out filename> + +This specifies filename to write the PKCS#12 file to. Standard output is used +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. + +=item B<-inkey filename> + +file to read private key from. If not present then a private key must be present +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. + +=item B<-certfile filename> + +A filename to read additional certificates from. + +=item B<-caname friendlyname> + +This specifies the "friendly name" for other certificates. This option may be +used multiple times to specify names for all certificates in the order they +appear. Netscape ignores friendly names on other certificates whereas MSIE +displays them. + +=item B<-pass password> + +the PKCS#12 file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpass var> + +read the PKCS#12 file password from the environment variable B. + +=item B<-chain> + +if this option is present then an attempt is made to include the entire +certificate chain of the user certificate. The standard CA store is used +for this search. If the search fails it is considered a fatal error. + +=item B<-descert> + +encrypt the certificate using triple DES, this may render the PKCS#12 +file unreadable by some "export grade" software. By default the private +key is encrypted using triple DES and the certificate using 40 bit RC2. + +=item B<-keypbe alg>, B<-certpbe alg> + +these options allow the algorithm used to encrypt the private key and +certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms +can be selected it is advisable only to use PKCS#12 algorithms. See the list +in the B section for more information. + +=item B<-keyex|-keysig> + +specifies that the private key is to be used for key exchange or just signing. +This option is only interpreted by MSIE and similar MS software. Normally +"export grade" software will only allow 512 bit RSA keys to be used for +encryption purposes but arbitrary length keys for signing. The B<-keysig> +option marks the key for signing only. Signing only keys can be used for +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<-nomaciter>, B<-noiter> + +these options affect the iteration counts on the MAC and key algorithms. +Unless you wish to produce files compatible with MSIE 4.0 you should leave +these options alone. + +To discourage attacks by using large dictionaries of common passwords the +algorithm that derives keys from passwords can have an iteration count applied +to it: this causes a certain part of the algorithm to be repeated and slows it +down. The MAC is used to check the file integrity but since it will normally +have the same password as the keys and certificates it could also be attacked. +By default both MAC and encryption iteration counts are set to 2048, using +these options the MAC and encryption iteration counts can be set to 1, since +this reduces the file security you should not use these options unless you +really have to. Most software supports both MAC and key iteration counts. +MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> +option. + +=item B<-maciter> + +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. + +=back + +=head1 NOTES + +Although there are a large number of options most of them are very rarely +used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used +for PKCS#12 file creation B<-export> and B<-name> are also used. + +The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption +algorithms for private keys and certificates to be specified. Normally +the defaults are fine but occasionally software can't handle triple DES +encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can +be used to reduce the private key encryption to 40 bit RC2. A complete +description of all algorithms is contained in the B manual page. + +=head1 EXAMPLES + +Parse a PKCS#12 file and output it to a file: + + openssl pkcs12 -in file.p12 -out file.pem + +Output only client certificates to a file: + + openssl pkcs12 -in file.p12 -clcerts -out file.pem + +Don't encrypt the private key: + + openssl pkcs12 -in file.p12 -out file.pem -nodes + +Print some info about a PKCS#12 file: + + openssl pkcs12 -in file.p12 -info -noout + +Create a PKCS#12 file: + + openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" + +Include some extra certificates: + + openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ + -certfile othercerts.pem + +=head1 BUGS + +Some would argue that the PKCS#12 standard is one big bug :-) + +Need password options for the PEM files: this will probably be fixed before +release. + +=head1 SEE ALSO + +pkcs8(1) + diff --git a/doc/apps/pkcs7.pod b/doc/apps/pkcs7.pod new file mode 100644 index 0000000000..0514c5d667 --- /dev/null +++ b/doc/apps/pkcs7.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +pkcs7 - PKCS#7 utility + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-print_certs>] +[B<-text>] +[B<-noout>] + +=head1 DESCRIPTION + +The B command processes PKCS#7 files in DER or PEM format. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format. B format is DER encoded PKCS#7 +v1.5 structure.B (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=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 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<-print_certs> + +prints out any certificates or CRLs contained in the file. They are +preceded by their subject and issuer names in one line format. + +=item B<-text> + +prints out certificates details in full rather than just subject and +issuer names. + +=item B<-noout> + +don't output the encoded version of the PKCS#7 structure (or certificates +is B<-print_certs> is set). + +=back + +=head1 EXAMPLES + +Convert a PKCS#7 file from PEM to DER: + + openssl pkcs7 -in file.pem -outform DER -out file.der + +Output all certificates in a file: + + openssl pkcs7 -in file.pem -print_certs -out certs.pem + +=head1 RESTRICTIONS + +There is no option to print out all the fields of a PKCS#7 file. + +This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they +cannot currently parse, for example, the new CMS as described in RFC2630. + +=head1 SEE ALSO + +crl2pkcs7(1) + +=cut diff --git a/doc/apps/pkcs8.pod b/doc/apps/pkcs8.pod new file mode 100644 index 0000000000..171b58b4b8 --- /dev/null +++ b/doc/apps/pkcs8.pod @@ -0,0 +1,224 @@ +=pod + +=head1 NAME + +pkcs8 - PKCS#8 format private key conversion tool + +=head1 SYNOPSIS + +B B +[B<-topk8>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin password>] +[B<-envpassin var>] +[B<-out filename>] +[B<-passout password>] +[B<-envpassout var>] +[B<-noiter>] +[B<-nocrypt>] +[B<-nooct>] +[B<-v2 alg>] +[B<-v1 alg>] + +=head1 DESCRIPTION + +The B command processes private keys in PKCS#8 format. It can handle +both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo +format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-topk8> + +Normally a PKCS#8 private key is expected on input and a traditional format +private key will be written. With the B<-topk8> option the situation is +reversed: it reads a traditional format private key and writes a PKCS#8 +format key. + +=item B<-inform DER|PEM> + +This specifies the input format. If a PKCS#8 format key is expected on input +then either a B or B encoded version of a PKCS#8 key will be +expected. Otherwise the B or B format of the traditional format +private key is used. + +=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 password> + +the input file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassin var> + +read the input file password from the environment variable B. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output by +default. If any encryption options are set then a pass phrase will be +prompted for. The output filename should B be the same as the input +filename. + +=item B<-passout password> + +the output file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassout var> + +read the output file password from the environment variable B. + +=item B<-nocrypt> + +PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo +structures using an appropriate password based encryption algorithm. With +this option an unencrypted PrivateKeyInfo structure is expected or output. +This option does not encrypt private keys at all and should only be used +when absolutely necessary. Certain software such as some versions of Java +code signing software used unencrypted private keys. + +=item B<-nooct> + +This option generates private keys in a broken format that some software +uses. Specifically the private key should be enclosed in a OCTET STRING +but some software just includes the structure itself without the +surrounding OCTET STRING. + +=item B<-v2 alg> + +This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8 +private keys are encrypted with the password based encryption algorithm +called B this uses 56 bit DES encryption but it +was the strongest encryption algorithm supported in PKCS#5 v1.5. Using +the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any +encryption algorithm such as 168 bit triple DES or 128 bit RC2 however +not many implementations support PKCS#5 v2.0 yet. If you are just using +private keys with OpenSSL then this doesn't matter. + +The B argument is the encryption algorithm to use, valid values include +B, B and B. It is recommended that B is used. + +=item B<-v1 alg> + +This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete +list of possible algorithms is included below. + +=back + +=head1 NOTES + +The encrypted form of a PEM encode PKCS#8 files uses the following +headers and footers: + + -----BEGIN ENCRYPTED PRIVATE KEY----- + -----END ENCRYPTED PRIVATE KEY----- + +The unencrypted form uses: + + -----BEGIN PRIVATE KEY----- + -----END PRIVATE KEY----- + +Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration +counts are more secure that those encrypted using the traditional +SSLeay compatible formats. So if additional security is considered +important the keys should be converted. + +The default encryption is only 56 bits because this is the encryption +that most current implementations of PKCS#8 will support. + +Some software may use PKCS#12 password based encryption algorithms +with PKCS#8 format private keys: these are handled automatically +but there is no option to produce them. + +It is possible to write out DER encoded encrypted private keys in +PKCS#8 format because the encryption details are included at an ASN1 +level whereas the traditional format includes them at a PEM level. + +=head1 PKCS#5 v1.5 and PKCS#12 algorithms. + +Various algorithms can be used with the B<-v1> command line option, +including PKCS#5 v1.5 and PKCS#12. These are described in more detail +below. + +=over 4 + +=item B + +These algorithms were included in the original PKCS#5 v1.5 specification. +They only offer 56 bits of protection since they both use DES. + +=item B + +These algorithms are not mentioned in the original PKCS#5 v1.5 specification +but they use the same key derivation algorithm and are supported by some +software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or +56 bit DES. + +=item B + +These algorithms use the PKCS#12 password based encryption algorithm and +allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. + +=back + +=head1 EXAMPLES + +Convert a private from traditional to PKCS#5 v2.0 format using triple +DES: + + openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem + +Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm +(DES): + + openssl pkcs8 -in key.pem -topk8 -out enckey.pem + +Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm +(3DES): + + openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES + +Read a DER unencrypted PKCS#8 format private key: + + openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem + +Convert a private key from any PKCS#8 format to traditional format: + + openssl pkcs8 -in pk8.pem -out key.pem + +=head1 STANDARDS + +Test vectors from this implementation were posted to the pkcs-tng mailing +list using triple DES, DES and RC2 with high iteration counts, several +people confirmed that they could decrypt the private keys produced and +Therefore it can be assumed that the PKCS#5 v2.0 implementation is +reasonably accurate at least as far as these algorithms are concerned. + +=head1 BUGS + +There should be an option that prints out the encryption algorithm +in use and other details such as the iteration count. + +PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private +key format for OpenSSL: for compatibility several of the utilities use +the old format at present. + +=head1 SEE ALSO + +dsa(1), rsa(1), genrsa(1), gendsa(1) + +=cut diff --git a/doc/apps/req.pod b/doc/apps/req.pod new file mode 100644 index 0000000000..e836f187ac --- /dev/null +++ b/doc/apps/req.pod @@ -0,0 +1,530 @@ + +=pod + +=head1 NAME + +req - PKCS#10 certificate and certificate generating utility. + +=head1 SYNOPSIS + +B B +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin password>] +[B<-envpassin var>] +[B<-out filename>] +[B<-passout password>] +[B<-envpassout var>] +[B<-text>] +[B<-noout>] +[B<-verify>] +[B<-modulus>] +[B<-new>] +[B<-newkey rsa:bits>] +[B<-newkey dsa:file>] +[B<-nodes>] +[B<-key filename>] +[B<-keyform PEM|DER>] +[B<-keyout filename>] +[B<-[md5|sha1|md2|mdc2]>] +[B<-config filename>] +[B<-x509>] +[B<-days n>] +[B<-noasn1-kludge>] +[B<-extensions section>] +[B<-reqexts section>] + +=head1 DESCRIPTION + +The B command primarily creates and processes certificate requests +in PKCS#10 format. It can additionally create self signed certificates +for use as root CAs for example. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|PEM> + +This specifies the input format. The B option uses an ASN1 DER encoded +form compatible with the PKCS#10. The B form is the default format: it +consists of the B format base64 encoded with additional header and +footer lines. + +=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 request from or standard input +if this option is not specified. A request is only read if the creation +options (B<-new> and B<-newkey>) are not specified. + +=item B<-passin password> + +the input file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassin var> + +read the input file password from the environment variable B. + +=item B<-out filename> + +This specifies the output filename to write to or standard output by +default. + +=item B<-passout password> + +the output file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassout var> + +read the output file password from the environment variable B. + +=item B<-text> + +prints out the certificate request in text form. + +=item B<-noout> + +this option prevents output of the encoded version of the request. + +=item B<-modulus> + +this option prints out the value of the modulus of the public key +contained in the request. + +=item B<-verify> + +verifies the signature on the request. + +=item B<-new> + +this option generates a new certificate request. It will prompt +the user for the relevant field values. The actual fields +prompted for and their maximum and minimum sizes are specified +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<-newkey arg> + +this option creates a new certificate request and a new private +key. The argument takes one of two forms. B, where +B is the number of bits, generates an RSA key B +in size. B generates a DSA key using the parameters +in the file B. + +=item B<-key filename> + +This specifies the file to read the private key from. It also +accepts PKCS#8 format private keys for PEM format files. + +=item B<-keyform PEM|DER> + +the format of the private key file specified in the B<-key> +argument. PEM is the default. + +=item B<-keyout filename> + +this gives the filename to write the newly created private key to. +If this option is not specified then the filename present in the +configuration file is used. + +=item B<-nodes> + +if this option is specified then if a private key is created it +will not be encrypted. + +=item B<-[md5|sha1|md2|mdc2]> + +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. + +=item B<-config filename> + +this allows an alternative configuration file to be specified, +this overrides the compile time filename or any specified in +the B environment variable. + +=item B<-x509> + +this option outputs a self signed certificate instead of a certificate +request. This is typically used to generate a test certificate or +a self signed root CA. The extensions added to the certificate +(if any) are specified in the configuration file. + +=item B<-days n> + +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 +extensions (if the B<-x509> option is present) or certificate +request extensions. This allows several different sections to +be used in the same configuration file to specify requests for +a variety of purposes. + +=item B<-asn1-kludge> + +by default the B command outputs certificate requests containing +no attributes in the correct PKCS#10 format. However certain CAs will only +accept requests containing no attributes in an invalid form: this +option produces this invalid format. + +More precisely the B in a PKCS#10 certificate request +are defined as a B. They are B so +if no attributes are present then they should be encoded as an +empty B. The invalid form does not include the empty +B whereas the correct form does. + +It should be noted that very few CAs still require the use of this option. + +=back + +=head1 CONFIGURATION FILE FORMAT + +The configuration options are specified in the B section of +the configuration file. As with all configuration files if no +value is specified in the specific section (i.e. B) then +the initial unnamed or B section is searched too. + +The options available are described in detail below. + +=over 4 + +=item B + +The passwords for the input private key file (if present) and +the output private key file (if one will be created). The +command line options B, B, B and +B override the configuration file values. + +=item B + +This specifies the default key size in bits. If not specified then +512 is used. It is used if the B<-new> option is used. It can be +overridden by using the B<-newkey> option. + +=item B + +This is the default filename to write a private key to. If not +specified the key is written to standard output. This can be +overridden by the B<-keyout> option. + +=item B + +This specifies a file containing additional B. +Each line of the file should consist of the numerical form of the +object identifier followed by white space then the short name followed +by white space and finally the long name. + +=item B + +This specifies a section in the configuration file containing extra +object identifiers. Each line should consist of the short name of the +object identifier followed by B<=> and the numerical form. The short +and long names are the same when this option is used. + +=item B + +This specifies a filename in which random number seed information is +placed and read from. It is used for private key generation. + +=item B + +If this is set to B then if a private key is generated it is +B encrypted. This is equivalent to the B<-nodes> command line +option. For compatibility B is an equivalent option. + +=item B + +This option specifies the digest algorithm to use. Possible values +include B. If not present then MD5 is used. This +option can be overridden on the command line. + +=item B + +This option masks out the use of certain string types in certain +fields. Most users will not need to change this option. + +It can be set to several values B which is also the default +option uses PrintableStrings, T61Strings and BMPStrings if the +B value is used then only PrintableStrings and BMPStrings will +be used. This follows the PKIX recommendation in RFC2459. If the +B option is used then only UTF8Strings will be used: this +is the PKIX recommendation in RFC2459 after 2003. Finally the B +option just uses PrintableStrings and T61Strings: certain software has +problems with BMPStrings and UTF8Strings: in particular Netscape. + +=item B + +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. + +=item B + +this specifies the configuration file section containing a list of +extensions to add to certificate generated when the B<-x509> switch +is used. It can be overridden by the B<-extensions> command line switch. + +=item B + +if set to the value B this disables prompting of certificate fields +and just takes values from the config file directly. It also changes the +expected format of the B and B sections. + +=item B + +this specifies the section containing any request attributes: its format +is the same as B. Typically these may contain the +challengePassword or unstructuredName types. They are currently ignored +by OpenSSL's request signing utilities but some CAs might want them. + +=item B + +This specifies the section containing the distinguished name fields to +prompt for when generating a certificate or certificate request. The format +is described in the next section. + +=back + +=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT + +There are two separate formats for the distinguished name and attribute +sections. If the B option is set to B then these sections +just consist of field names and values: for example, + + CN=My Name + OU=My Organization + emailAddress=someone@somehere.org + +This allows external programs (e.g. GUI based) to generate a template file +with all the field names and values and just pass it to B. An example +of this kind of configuration files is contained in the B section. + +Alternatively if the B option is absent or not set to B the the +file contains field prompting information. It consists of lines of the form: + + fieldName="prompt" + fieldName_default="default field value" + fieldName_min= 2 + fieldName_max= 4 + +"fieldName" is the field name being used, for example commonName (or CN). +The "prompt" string is used to ask the user to enter the relevant +details. If the user enters nothing then the default value is used if no +default value is present then the field is omitted. A field can +still be omitted if a default value is present if the user just +enters the '.' character. + +The number of characters entered must be between the fieldName_min and +fieldName_max limits: there may be additional restrictions based +on the field being used (for example countryName can only ever be +two characters long and must fit in a PrintableString). + +Some fields (such as organizationName) can be used more than once +in a DN. This presents a problem because configuration files will +not recognize the same name occurring twice. To avoid this problem +if the fieldName contains an some characters followed by a full stop +they will be ignored. So for example a second organizationName can +be input by calling it "1.organizationName". + +The actual permitted field names are any object identifier short or +long names. These are compiled into OpenSSL and include the usual +values such as commonName, countryName, localityName, organizationName, +organizationUnitName, stateOrPrivinceName. Additionally emailAddress +is include as well as name, surname, givenName initials and dnQualifier +are supported. + +Additional object identifiers can be defined with the B or +B options in the configuration file. Any additional fields +will be treated as though they were a DirectoryString. + + +=head1 EXAMPLES + +Examine and verify certificate request: + + openssl req -in req.pem -text -verify -noout + +Create a private key and then generate a certificate request from it: + + openssl genrsa -out key.pem 1024 + openssl req -new -key key.pem -out req.pem + +The same but just using req: + + openssl req -newkey rsa:1024 -keyout key.pem -out req.pem + +Generate a self signed root certificate: + + openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem + +Example of a file pointed to by the B option: + + 1.2.3.4 shortName A longer Name + 1.2.3.6 otherName Other longer Name + +Example of a section pointed to by B making use of variable +expansion: + + testoid1=1.2.3.5 + testoid2=${testoid1}.6 + +Sample configuration file prompting for field values: + + [ req ] + default_bits = 1024 + default_keyfile = privkey.pem + distinguished_name = req_distinguished_name + attributes = req_attributes + x509_extensions = v3_ca + + dirstring_type = nobmp + + [ req_distinguished_name ] + countryName = Country Name (2 letter code) + countryName_default = AU + countryName_min = 2 + countryName_max = 2 + + localityName = Locality Name (eg, city) + + organizationalUnitName = Organizational Unit Name (eg, section) + + commonName = Common Name (eg, YOUR name) + commonName_max = 64 + + emailAddress = Email Address + emailAddress_max = 40 + + [ req_attributes ] + challengePassword = A challenge password + challengePassword_min = 4 + challengePassword_max = 20 + + [ v3_ca ] + + subjectKeyIdentifier=hash + authorityKeyIdentifier=keyid:always,issuer:always + basicConstraints = CA:true + +Sample configuration containing all field values: + + + RANDFILE = $ENV::HOME/.rnd + + [ req ] + default_bits = 1024 + default_keyfile = keyfile.pem + distinguished_name = req_distinguished_name + attributes = req_attributes + prompt = no + output_password = mypass + + [ req_distinguished_name ] + C = GB + ST = Test State or Province + L = Test Locality + O = Organization Name + OU = Organizational Unit Name + CN = Common Name + emailAddress = test@email.address + + [ req_attributes ] + challengePassword = A challenge password + + +=head1 NOTES + +The header and footer lines in the B format are respectively: + + -----BEGIN CERTIFICATE REQUEST---- + -----END CERTIFICATE REQUEST---- + +some software (some versions of Netscape certificate server) instead needs: + + -----BEGIN NEW CERTIFICATE REQUEST---- + -----END NEW CERTIFICATE REQUEST---- + +but is otherwise compatible. Either form is accepted on input. + +The certificate requests generated by B with MSIE have extensions +added. It includes the B extension which determines the type of +key (signature only or general purpose) and any additional OIDs entered +by the script in an extendedKeyUsage extension. + +=head1 DIAGNOSTICS + +The following messages are frequently asked about: + + Using configuration from /some/path/openssl.cnf + Unable to load config info + +This is followed some time later by... + + unable to find 'distinguished_name' in config + problems making Certificate Request + +The first error message is the clue: it can't find the configuration +file! Certain operations (like examining a certificate request) don't +need a configuration file so its use isn't enforced. Generation of +certificates or requests however does need a configuration file. This +could be regarded as a bug. + +Another puzzling message is this: + + Attributes: + a0:00 + +this is displayed when no attributes are present and the request includes +the correct empty B structure (the DER encoding of which is 0xa0 +0x00). If you just see: + + Attributes: + +then the B is missing and the encoding is technically invalid (but +it is tolerated). See the description of the command line option B<-asn1-kludge> +for more information. + +=head1 ENVIRONMENT VARIABLES + +The variable B if defined allows an alternative configuration +file location to be specified, it will be overridden by the B<-config> command +line switch if it is present. For compatibility reasons the B +environment variable serves the same purpose but its use is discouraged. + +=head1 BUGS + +OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively +treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. +This can cause problems if you need characters that aren't available in +PrintableStrings and you don't want to or can't use BMPStrings. + +As a consequence of the T61String handling the only correct way to represent +accented characters in OpenSSL is to use a BMPString: unfortunately Netscape +currently chokes on these. If you have to use accented characters with Netscape +and MSIE then you currently need to use the invalid T61String form. + +The current prompting is not very friendly. It doesn't allow you to confirm what +you've just entered. Other things like extensions in certificate requests are +statically defined in the configuration file. Some of these: like an email +address in subjectAltName should be input by the user. + +=head1 SEE ALSO + +x509(1), ca(1), genrsa(1), gendsa(1), config(5) + +=cut diff --git a/doc/apps/rsa.pod b/doc/apps/rsa.pod new file mode 100644 index 0000000000..05c64eb470 --- /dev/null +++ b/doc/apps/rsa.pod @@ -0,0 +1,160 @@ + +=pod + +=head1 NAME + +rsa - RSA key processing tool + +=head1 SYNOPSIS + +B B +[B<-inform PEM|NET|DER>] +[B<-outform PEM|NET|DER>] +[B<-in filename>] +[B<-passin password>] +[B<-envpassin var>] +[B<-out filename>] +[B<-passout password>] +[B<-envpassout var>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-text>] +[B<-noout>] +[B<-modulus>] +[B<-check>] +[B<-pubin>] +[B<-pubout>] + +=head1 DESCRIPTION + +The B command processes RSA keys. They can be converted between various +forms and their components printed out. B this command uses the +traditional SSLeay compatible format for private key encryption: newer +applications should use the more secure PKCS#8 format using the B +utility. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-inform DER|NET|PEM> + +This specifies the input format. The B option uses an ASN1 DER encoded +form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format. +The B form is the default format: it consists of the B format base64 +encoded with additional header and footer lines. On input PKCS#8 format private +keys are also accepted. The B 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. + +=item B<-outform DER|NET|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 password> + +the input file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassin var> + +read the input file password from the environment variable B. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output by +is not specified. If any encryption options are set then a pass phrase will be +prompted for. The output filename should B be the same as the input +filename. + +=item B<-passout password> + +the output file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpassout var> + +read the output file password from the environment variable B. + +=item B<-des|-des3|-idea> + +These options encrypt the private key with the DES, triple DES, or the +IDEA ciphers respectively before outputting it. A pass phrase is prompted for. +If none of these options is specified the key is written in plain text. This +means that using the B utility to read in an encrypted key with no +encryption option can be used to remove the pass phrase from a key, or by +setting the encryption options it can be use to add or change the pass phrase. +These options can only be used with PEM format output files. + +=item B<-text> + +prints out the various public or private key components in +plain text in addition to the encoded version. + +=item B<-noout> + +this option prevents output of the encoded version of the key. + +=item B<-modulus> + +this option prints out the value of the modulus of the key. + +=item B<-check> + +this option checks the consistency of an RSA private key. + +=item B<-pubin> + +by default a private key is input file with this option a public key is input +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. + +=back + +=head1 NOTES + +The PEM private key format uses the header and footer lines: + + -----BEGIN RSA PRIVATE KEY----- + -----END RSA PRIVATE KEY----- + +=head1 EXAMPLES + +To remove the pass phrase on an RSA private key: + +C + +To encrypt a private key using triple DES: + +C + +To convert a private key from PEM to DER format: + +C + +To print out the components of a private key to standard output: + +C + +To just output the public part of a private key: + +C + +=head1 SEE ALSO + +pkcs8(1), dsa(1), genrsa(1), gendsa(1) + +=cut diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod new file mode 100644 index 0000000000..cd9093eaba --- /dev/null +++ b/doc/apps/s_client.pod @@ -0,0 +1,211 @@ + +=pod + +=head1 NAME + +s_client - SSL/TLS client program + +=head1 SYNOPSIS + +B B +[B<-connect> host:port>] +[B<-verify depth>] +[B<-cert filename>] +[B<-key filename>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-reconnect>] +[B<-pause>] +[B<-showcerts>] +[B<-debug>] +[B<-nbio_test>] +[B<-state>] +[B<-nbio>] +[B<-crlf>] +[B<-quiet>] +[B<-ssl2>] +[B<-ssl3>] +[B<-tls1>] +[B<-no_ssl2>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-bugs>] +[B<-cipher cipherlist>] + +=head1 DESCRIPTION + +The B command implements a generic SSL/TLS client which connects +to a remote host using SSL/TLS. It is a I useful diagnostic tool for +SSL servers. + +=head1 OPTIONS + +=over 4 + +=item B<-connect host:port> + +This specifies the host and optional port to connect to. If not specified +then an attempt is made to connect to the local host on port 4433. + +=item B<-cert certname> + +The certificate to use, if one is requested by the server. The default is +not to use a certificate. + +=item B<-key keyfile> + +The private key to use. If not specified then the certificate file will +be used. + +=item B<-verify depth> + +The verify depth to use. This specifies the maximum length of the +server certificate chain and turns on server certificate verification. +Currently the verify operation continues after errors so all the problems +with a certificate chain can be seen. As a side effect the connection +will never fail due to a server certificate verify failure. + +=item B<-CApath directory> + +The directory to use for server certificate verification. This directory +must be in "hash format", see B for more information. These are +also used when building the client certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during server authentication +and to use when attempting to build the client certificate chain. + +=item B<-reconnect> + +reconnects to the same server 5 times using the same session ID, this can +be used as a test that session caching is working. + +=item B<-pause> + +pauses 1 second between each read and write call. + +=item B<-showcerts> + +display the whole server certificate chain: normally only the server +certificate itself is displayed. + +=item B<-prexit> + +print session information when the program exits. This will always attempt +to print out information even if the connection fails. Normally information +will only be printed out once if the connection succeeds. This option is useful +because the cipher in use may be renegotiated or the connection may fail +because a client certificate is required or is requested only after an +attempt is made to access a certain URL. Note: the output produced by this +option is not always accurate because a connection might never have been +established. + +=item B<-state> + +prints out the SSL session states. + +=item B<-debug> + +print extensive debugging information including a hex dump of all traffic. + +=item B<-nbio_test> + +tests non blocking I/O + +=item B<-nbio> + +turns on non blocking I/O + +=item B<-crlf> + +this option translated a line feed from the terminal into CR+LF as required +by some servers. + +=item B<-quiet> + +inhibit printing of session and certificate information. + +=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 +the initial handshake uses a method which should be compatible with all +servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. + +Unfortunately there are a lot of ancient and broken servers in use which +cannot handle this technique and will fail to connect. Some servers only +work if TLS is turned off with the B<-no_tls> option others will only +support SSL v2 and may need the B<-ssl2> option. + +=item B<-bugs> + +there are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-cipher cipherlist> + +this allows the cipher list sent by the client to be modified. See the +B command for more information. + +=back + +=head1 CONNECTED COMMANDS + +If a connection is established with an SSL server then any data received +from the server is displayed and any key presses will be sent to the +server. If the line begins with an B then the session will be +renegotiated. If the line begins with a B the connection will be closed +down. + +=head1 NOTES + +B can be used to debug SSL servers. To connect to an SSL HTTP +server the command: + + openssl s_client -connect servername:443 + +would typically be used (https uses port 443). If the connection succeeds +then an HTTP command can be given such as "GET /" to retrieve a web page. + +If the handshake fails then there are several possible causes, if it is +nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, +B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> can be tried +in case it is a buggy server. In particular you should play with these +options B submitting a bug report to an OpenSSL mailing list. + +A frequent problem when attempting to get client certificates working +is that a web client complains it has no certificates or gives an empty +list to choose from. This is normally because the server is not sending +the clients certificate authority in its "acceptable CA list" when it +requests a certificate. By using B the CA list can be viewed +and checked. However some servers only request client authentication +after a specific URL is requested. To obtain the list in this case it +is necessary to use the B<-prexit> command and send an HTTP request +for an appropriate page. + +If a certificate is specified on the command line using the B<-cert> +option it will not be used unless the server specifically requests +a client certificate. Therefor merely including a client certificate +on the command line is no guarantee that the certificate works. + +If there are problems verifying a server certificate then the +B<-showcerts> option can be used to show the whole chain. + +=head1 BUGS + +Because this program has a lot of options and also because some of +the techniques used are rather old, the C source of s_client is rather +hard to read and not a model of how things should be done. A typical +SSL client program would be much simpler. + +The B<-verify> option should really exit if the server verification +fails. + +The B<-prexit> option is a bit of a hack. We should really report +information whenever a session is renegotiated. + +=head1 SEE ALSO + +sess_id(1), s_server(1), ciphers(1) + +=cut diff --git a/doc/apps/s_server.pod b/doc/apps/s_server.pod new file mode 100644 index 0000000000..5b6a20221d --- /dev/null +++ b/doc/apps/s_server.pod @@ -0,0 +1,262 @@ + +=pod + +=head1 NAME + +s_server - SSL/TLS server program + +=head1 SYNOPSIS + +B B +[B<-accept port>] +[B<-context id>] +[B<-verify depth>] +[B<-Verify depth>] +[B<-cert filename>] +[B<-key keyfile>] +[B<-dcert filename>] +[B<-dkey keyfile>] +[B<-dhparam filename>] +[B<-nbio>] +[B<-nbio_test>] +[B<-crlf>] +[B<-debug>] +[B<-state>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-nocert>] +[B<-cipher cipherlist>] +[B<-quiet>] +[B<-no_tmp_rsa>] +[B<-ssl2>] +[B<-ssl3>] +[B<-tls1>] +[B<-no_ssl2>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-no_dhe>] +[B<-bugs>] +[B<-hack>] +[B<-www>] +[B<-WWW>] + +=head1 DESCRIPTION + +The B command implements a generic SSL/TLS server which listens +for connections on a given port using SSL/TLS. + +=head1 OPTIONS + +=over 4 + +=item B<-accept port> + +the TCP port to listen on for connections. If not specified 4433 is used. + +=item B<-context id> + +sets the SSL context id. If a client certificate is being requested then +this option must be set. It can be given any string value. + +=item B<-cert certname> + +The certificate to use, most servers cipher suites require the use of a +certificate and some require a certificate with a certain public key type: +for example the DSS cipher suites require a certificate containing a DSS +(DSA) key. If not specified then the filename "server.pem" will be used. + +=item B<-key keyfile> + +The private key to use. If not specified then the certificate file will +be used. + +=item B<-dcert filename>, B<-dkey keyname> + +specify an additional certificate and private key, these behave in the +same manner as the B<-cert> and B<-key> options except there is no default +if they are not specified (no additional certificate and key is used). As +noted above some cipher suites require a certificate containing a key of +a certain type. Some cipher suites need a certificate carrying an RSA key +and some a DSS (DSA) key. By using RSA and DSS certificates and keys +a server can support clients which only support RSA or DSS cipher suites +by using an appropriate certificate. + +=item B<-nocert> + +if this option is set then no certificate is used. This restricts the +cipher suites available to the anonymous ones (currently just anonymous +DH). + +=item B<-dhparam filename> + +the DH parameter file to use. The ephemeral DH cipher suites generate keys +using a set of DH parameters. If not specified then an attempt is made to +load the parameters from the server certificate file. If this fails then +a static set of parameters hard coded into the s_server program will be used. + +=item B<-nodhe> + +if this option is set then no DH parameters will be loaded effectively +disabling the ephemeral DH cipher suites. + +=item B<-no_tmp_rsa> + +certain export cipher suites sometimes use a temporary RSA key, this option +disables temporary RSA key generation. + +=item B<-verify depth>, B<-Verify depth> + +The verify depth to use. This specifies the maximum length of the +client certificate chain and makes the server request a certificate from +the client. With the B<-verify> option a certificate is requested but the +client does not have to send one, with the B<-Verify> option the client +must supply a certificate or an error occurs. + +=item B<-CApath directory> + +The directory to use for client certificate verification. This directory +must be in "hash format", see B for more information. These are +also used when building the server certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during client authentication +and to use when attempting to build the server certificate chain. The list +is also used in the list of acceptable client CAs passed to the client when +a certificate is requested. + +=item B<-state> + +prints out the SSL session states. + +=item B<-debug> + +print extensive debugging information including a hex dump of all traffic. + +=item B<-nbio_test> + +tests non blocking I/O + +=item B<-nbio> + +turns on non blocking I/O + +=item B<-crlf> + +this option translated a line feed from the terminal into CR+LF. + +=item B<-quiet> + +inhibit printing of session and certificate information. + +=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 +the initial handshake uses a method which should be compatible with all +servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. + +=item B<-bugs> + +there are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-hack> + +this option enables a further workaround for some some early Netscape +SSL code (?). + +=item B<-cipher cipherlist> + +this allows the cipher list sent by the client to be modified. See the +B command for more information. + +=item B<-www> + +sends a status message back to the client when it connects. This includes +lots of information about the ciphers used and various session parameters. +The output is in HTML format so this option will normally be used with a +web browser. + +=item B<-WWW> + +emulates a simple web server. Pages will be resolved relative to the +current directory, for example if the URL https://myhost/page.html is +requested the file ./page.html will be loaded. + +=back + +=head1 CONNECTED COMMANDS + +If a connection request is established with an SSL client and neither the +B<-www> nor the B<-WWW> option has been used then normally any data received +from the client is displayed and any key presses will be sent to the client. + +Certain single letter commands are also recognised which perform special +operations: these are listed below. + +=over 4 + +=item B + +end the current SSL connection but still accept new connections. + +=item B + +end the current SSL connection and exit. + +=item B + +renegotiate the SSL session. + +=item B + +renegotiate the SSL session and request a client certificate. + +=item B

+ +send some plain text down the underlying TCP connection: this should +cause the client to disconnect due to a protocol violation. + +=item B + +print out some session cache status information. + +=back + +=head1 NOTES + +B can be used to debug SSL clients. To accept connections from +a web browser the command: + + openssl s_server -accept 443 -www + +can be used for example. + +Most web browsers (in particular Netscape and MSIE) only support RSA cipher +suites, so they cannot connect to servers which don't use a certificate +carrying an RSA key or a version of OpenSSL with RSA disabled. + +Although specifying an empty list of CAs when requesting a client certificate +is strictly speaking a protocol violation, some SSL clients interpret this to +mean any CA is acceptable. This is useful for debugging purposes. + +The session parameters can printed out using the B program. + +=head1 BUGS + +Because this program has a lot of options and also because some of +the techniques used are rather old, the C source of s_server is rather +hard to read and not a model of how things should be done. A typical +SSL server program would be much simpler. + +The output of common ciphers is wrong: it just gives the list of ciphers that +OpenSSL recognizes and the client supports. + +There should be a way for the B program to print out details of any +unknown cipher suites a client says it supports. + +=head1 SEE ALSO + +sess_id(1), s_client(1), ciphers(1) + +=cut diff --git a/doc/apps/smime.pod b/doc/apps/smime.pod new file mode 100644 index 0000000000..d0da967083 --- /dev/null +++ b/doc/apps/smime.pod @@ -0,0 +1,313 @@ +=pod + +=head1 NAME + +smime - S/MIME utility + +=head1 SYNOPSIS + +B B +[B<-encrypt>] +[B<-decrypt>] +[B<-sign>] +[B<-verify>] +[B<-pk7out>] +[B<-des>] +[B<-des3>] +[B<-rc2-40>] +[B<-rc2-64>] +[B<-rc2-128>] +[B<-in file>] +[B<-certfile file>] +[B<-signer file>] +[B<-recip file>] +[B<-in file>] +[B<-inkey file>] +[B<-out file>] +[B<-to addr>] +[B<-from ad>] +[B<-subject s>] +[B<-text>] +[cert.pem]... + +=head1 DESCRIPTION + +The B command handles S/MIME mail. It can encrypt, decrypt, sign and +verify S/MIME messages. + +=head1 COMMAND OPTIONS + +There are five 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. + +=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<-pk7out> + +takes an input message and writes out a PEM encoded PKCS#7 structure. + +=item B<-in filename> + +the input message to be encrypted or signed or the MIME message to +be decrypted or verified. + +=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<-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<-CAfile file> + +a file containing trusted CA certificates, only used with B<-verify>. + +=item B<-CApath dir> + +a directory containing trusted CA certificates, only used with +B<-verify>. This directory must be a standard certificate directory: that +is a hash of each subject name (using B) should be linked +to each certificate. + +=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128> + +the encryption algorithm to use. DES (56 bits), triple DES (168 bits) +or 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 is +used. Only used with B<-encrypt>. + +=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<-noverify> + +do not verify the signers certificate of a signed message. + +=item B<-nochain> + +do not do chain verification of signers certificates: that is don't +use the certificates in the signed message as untrusted CAs. + +=item B<-nosigs> + +don't try to verify the signatures on the 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<-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<-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. + +=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<-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. + +=item B + +one or more certificates of message recipients: used when encrypting +a message. + +=item B<-to, -from, -subject> + +the relevant mail headers. These are included outside the signed +portion of a message so they may be included manually. If signing +then many S/MIME mail clients check the signers certificate's email +address matches that specified in the From: address. + +=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 PKCS#7 enveloped data: PKCS#7 +encrypted data is used for other purposes. + +=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 PKCS#7 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 EXAMPLES + +Create a cleartext signed message: + + openssl smime -sign -in message.txt -text -out mail.msg + -signer mycert.pem + +Create and opaque signed message + + openssl smime -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 smime -sign -in in.txt -text -out mail.msg + -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem + +Send a signed message under Unix directly to sendmail, including headers: + + openssl smime -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 smime -verify -in mail.msg -signer user.pem -out signedtext.txt + +Send encrypted mail using triple DES: + + openssl smime -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 smime -sign -in ml.txt -signer my.pem -text | openssl -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 smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem + +=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. + +The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 +structures may cause parsing errors. + +=cut diff --git a/doc/apps/spkac.pod b/doc/apps/spkac.pod new file mode 100644 index 0000000000..75d58e772b --- /dev/null +++ b/doc/apps/spkac.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +spkac - SPKAC printing and generating utility + +=head1 SYNOPSIS + +B B +[B<-in filename>] +[B<-out filename>] +[B<-key keyfile>] +[B<-challenge string>] +[B<-spkac spkacname>] +[B<-spksect section>] +[B<-noout>] +[B<-verify>] + + +=head1 DESCRIPTION + +The B command processes Netscape signed public key and challenge +(SPKAC) files. It can print out their contents, verify the signature and +produce its own SPKACs from a supplied private key. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies the input filename to read from or standard input if this +option is not specified. Ignored if the B<-key> option is used. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-key keyfile> + +create an SPKAC file using the private key in B. The +B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if +present. + +=item B<-challenge string> + +specifies the challenge string if an SPKAC is being created. + +=item B<-spkac spkacname> + +allows an alternative name form the variable containing the +SPKAC. The default is "SPKAC". This option affects both +generated and input SPKAC files. + +=item B<-spksect section> + +allows an alternative name form the section containing the +SPKAC. The default is the default section. + +=item B<-noout> + +don't output the text version of the SPKAC (not used if an +SPKAC is being created). + +=item B<-verify> + +verifies the digital signature on the supplied SPKAC. + + +=back + +=head1 EXAMPLES + +Print out the contents of an SPKAC: + + openssl spkac -in spkac.cnf + +Verify the signature of an SPKAC: + + openssl spkac -in spkac.cnf -noout -verify + +Create an SPKAC using the challenge string "hello": + + openssl spkac -key key.pem -challenge hello -out spkac.cnf + +Example of an SPKAC, (long lines split up for clarity): + + SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\ + PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\ + PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\ + 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\ + 4= + +=head1 NOTES + +A created SPKAC with suitable DN components appended can be fed into +the B utility. + +SPKACs are typically generated by Netscape when a form is submitted +containing the B tag as part of the certificate enrollment +process. + +The challenge string permits a primitive form of proof of possession +of private key. By checking the SPKAC signature and a random challenge +string some guarantee is given that the user knows the private key +corresponding to the public key being certified. This is important in +some applications. Without this it is possible for a previous SPKAC +to be used in a "replay attack". + +=head1 SEE ALSO + +ca(1) + +=cut diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod new file mode 100644 index 0000000000..2ff261e29a --- /dev/null +++ b/doc/apps/verify.pod @@ -0,0 +1,273 @@ +=pod + +=head1 NAME + +pkcs7 - PKCS#7 utility + +=head1 SYNOPSIS + +B B +[B<-CApath directory>] +[B<-CAfile file>] +[B<-purpose purpose>] +[B<-untrusted file>] +[B<-help>] +[B<-verbose>] +[B<->] +[certificates] + + +=head1 DESCRIPTION + +The B command verifies certificate chains. + +=head1 COMMAND OPTIONS + +=over 4 + +=item B<-CApath directory> + +A directory of trusted certificates. The certificates should have names +of the form: hash.0 or have symbolic links to them of this +form ("hash" is the hashed certificate subject name: see the B<-hash> option +of the B utility). Under Unix the B script will automatically +create symbolic links to a directory of certificates. + +=item B<-CAfile file> + +A file of trusted certificates. The file should contain multiple certificates +in PEM format concatenated together. + +=item B<-untrusted file> + +A file of untrusted certificates. The file should contain multiple certificates + +=item B<-purpose purpose> + +the intended use for the certificate. Without this option no chain verification +will be done. Currently accepted uses are B, B, +B, B, B. See the B +section for more information. + +=item B<-help> + +prints out a usage message. + +=item B<-verbose> + +print extra information about the operations being performed. + +=item B<-> + +marks the last option. All arguments following this are assumed to be +certificate files. This is useful if the first certificate filename begins +with a B<->. + +=item B + +one or more certificates to verify. If no certificate filenames are included +then an attempt is made to read a certificate from standard input. They should +all be in PEM format. + + +=back + +=head1 VERIFY OPERATION + +The B program uses the same functions as the internal SSL and S/MIME +verification, therefore this description applies to these verify operations +too. + +There is one crucial difference between the verify operations performed +by the B program: wherever possible an attempt is made to continue +after an error whereas normally the verify operation would halt on the +first error. This allows all the problems with a certificate chain to be +determined. + +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. +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 +verify is a root certificate then an exact match must be found in the trusted +list. + +The second operation is to check every untrusted certificate's extensions for +consistency with the supplied purpose. If the B<-purpose> option is not included +then no checks are done. The supplied or "leaf" certificate must have extensions +compatible with the supplied purpose and all other certificates must also be valid +CA certificates. The precise extensions required are described in more detail in +the B section of the B utility. + +The third operation is to check the trust settings on the root CA. The root +CA should be trusted for the supplied purpose. For compatibility with previous +versions of SSLeay and OpenSSL a certificate with no trust settings is considered +to be valid for all purposes. + +The final operation is to check the validity of the certificate chain. The validity +period is checked against the current system time and the notBefore and notAfter +dates in the certificate. The certificate signatures are also checked at this +point. + +If all operations complete successfully then certificate is considered valid. If +any operation fails then the certificate is not valid. + +=head1 DIAGNOSTICS + +When a verify operation fails the output messages can be somewhat cryptic. The +general form of the error message is: + + server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) + error 24 at 1 depth lookup:invalid CA certificate + +The first line contains the name of the certificate being verified followed by +the subject name of the certificate. The second line contains the error number +and the depth. The depth is number of the certificate being verified when a +problem was detected starting with zero for the certificate being verified itself +then 1 for the CA that signed the certificate and so on. Finally a text version +of the error number is presented. + +An exhaustive list of the error codes and messages is shown below, this also +includes the name of the error code as defined in the header file x509_vfy.h +Some of the error codes are defined but never returned: these are described +as "unused". + +=over 4 + +=item B<0 X509_V_OK: ok> + +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. + +=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. + +=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> + +the certificate signature could not be decrypted. This means that the actual signature value +could not be determined rather than it not matching the expected value, this is only +meaningful for RSA keys. + +=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> + +the CRL signature could not be decrypted: this means that the actual signature value +could not be determined rather than it not matching the expected value. Unused. + +=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> + +the public key in the certificate SubjectPublicKeyInfo could not be read. + +=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> + +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. + +=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> + +the certificate is not yet valid: the notBefore date is after the current time. + +=item B<10 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> + +the CRL is not yet valid. Unused. + +=item B<11 X509_V_ERR_CERT_HAS_EXPIRED: Certificate has expired> + +the certificate has expired: that is the notAfter date is before the current time. + +=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> + +the CRL has expired. Unused. + +=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> + +the certificate notBefore field contains an invalid time. + +=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> + +the certificate notAfter field contains an invalid time. + +=item B<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. + +=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. + +=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> + +an error occurred trying to allocate memory. This should never happen. + +=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> + +the passed certificate is self signed and the same certificate cannot be found in the list of +trusted certificates. + +=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> + +the certificate chain could be built up using the untrusted certificates but the root could not +be found locally. + +=item B<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. + +=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> + +no signatures could be verified because the chain contains only one certificate and it is not +self signed. + +=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> + +the certificate chain length is greater than the supplied maximum depth. Unused. + +=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> + +the certificate has been revoked. Unused. + +=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> + +a CA certificate is invalid. Either it is not a CA or its extensions are not consistent +with the supplied purpose. + +=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> + +the basicConstraints pathlength parameter has been exceeded. + +=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> + +the supplied certificate cannot be used for the specified purpose. + +=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> + +the root CA is not marked as trusted for the specified purpose. + +=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> + +the root CA is marked to reject the specified purpose. + +=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> + +an application specific error. Unused. + +=back + +=head1 SEE ALSO + +x509(1) + +=cut diff --git a/doc/apps/version.pod b/doc/apps/version.pod new file mode 100644 index 0000000000..69421d52cb --- /dev/null +++ b/doc/apps/version.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +version - print version information + +=head1 SYNOPSIS + +B +[B<-a>] +[B<-v>] +[B<-b>] +[B<-o>] +[B<-f>] +[B<-p>] + +=head1 DESCRIPTION + +This command is used to print out version information about OpenSSL. + +=head1 OPTIONS + +=over 4 + +=item B<-a> + +all information, this is the same as setting all the other flags. + +=item B<-v> + +the current OpenSSL version. + +=item B<-b> + +the date the current version of OpenSSL was built. + +=item B<-o> + +option information: various options set when the library was built. + +=item B<-c> + +compilation flags. + +=item B<-p> + +platform setting. + +=back + +=head1 NOTES + +The output of B would typically be used when sending +in a bug report. + +=cut diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod new file mode 100644 index 0000000000..52ac949b18 --- /dev/null +++ b/doc/apps/x509.pod @@ -0,0 +1,541 @@ + +=pod + +=head1 NAME + +x509 - Certificate display and signing utility + +=head1 SYNOPSIS + +B B +[B<-inform DER|PEM|NET>] +[B<-outform DER|PEM|NET>] +[B<-keyform DER|PEM>] +[B<-CAform DER|PEM>] +[B<-CAkeyform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-serial>] +[B<-hash>] +[B<-subject>] +[B<-issuer>] +[B<-startdate>] +[B<-enddate>] +[B<-purpose>] +[B<-dates>] +[B<-modulus>] +[B<-fingerprint>] +[B<-alias>] +[B<-noout>] +[B<-trustout>] +[B<-clrtrust>] +[B<-clrreject>] +[B<-addtrust arg>] +[B<-addreject arg>] +[B<-setalias arg>] +[B<-days arg>] +[B<-signkey filename>] +[B<-x509toreq>] +[B<-req>] +[B<-CA filename>] +[B<-CAkey filename>] +[B<-CAcreateserial>] +[B<-CAserial filename>] +[B<-text>] +[B<-C>] +[B<-md2|-md5|-sha1|-mdc2>] +[B<-clrext>] +[B<-extfile filename>] +[B<-extensions section>] + +=head1 DESCRIPTION + +The B command is a multi purpose certificate utility. It can be +used to display certificate information, convert certificates to +various forms, sign certificate requests like a "mini CA" or edit +certificate trust settings. + +Since there are a large number of options they will split up into +various sections. + + +=head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS + +=over 4 + +=item B<-inform DER|PEM|NET> + +This specifies the input format normally the command will expect an X509 +certificate but this can change if other options such as B<-req> are +present. The DER format is the DER encoding of the certificate and PEM +is the base64 encoding of the DER encoding with header and footer lines +added. The NET option is an obscure Netscape server format that is now +obsolete. + +=item B<-outform DER|PEM|NET> + +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 certificate from or standard input +if this option is not specified. + +=item B<-out filename> + +This specifies the output filename to write to or standard output by +default. + +=item B<-md2|-md5|-sha1|-mdc2> + +the digest to use. This affects any signing or display option that uses a message +digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not +specified then MD5 is used. If the key being used to sign with is a DSA key then +this option has no effect: SHA1 is always used with DSA keys. + + +=back + +=head1 DISPLAY OPTIONS + +Note: the B<-alias> and B<-purpose> options are also display options +but are described in the B section. + +=over 4 + +=item B<-text> + +prints out the certificate in text form. Full details are output including the +public key, signature algorithms, issuer and subject names, serial number +any extensions present and any trust settings. + +=item B<-noout> + +this option prevents output of the encoded version of the request. + +=item B<-modulus> + +this option prints out the value of the modulus of the public key +contained in the certificate. + +=item B<-serial> + +outputs the certificate serial number. + +=item B<-hash> + +outputs the "hash" of the certificate subject name. This is used in OpenSSL to +form an index to allow certificates in a directory to be looked up by subject +name. + +=item B<-subject> + +outputs the subject name. + +=item B<-issuer> + +outputs the issuer name. + +=item B<-startdate> + +prints out the start date of the certificate, that is the notBefore date. + +=item B<-enddate> + +prints out the expiry date of the certificate, that is the notAfter date. + +=item B<-dates> + +prints out the start and expiry dates of a certificate. + +=item B<-fingerprint> + +prints out the digest of the DER encoded version of the whole certificate. + +=item B<-C> + +this outputs the certificate in the form of a C source file. + +=back + +=head1 TRUST SETTINGS + +Please note these options are currently experimental and may well change. + +A B is an ordinary certificate which has several +additional pieces of information attached to it such as the permitted +and prohibited uses of the certificate and an "alias". + +Normally when a certificate is being verified at least one certificate +must be "trusted". By default a trusted certificate must be stored +locally and must be a root CA: any certificate chain ending in this CA +is then usable for any purpose. + +Trust settings currently are only used with a root CA. They allow a finer +control over the purposes the root CA can be used for. For example a CA +may be trusted for SSL client but not SSL server use. + +See the description of the B utility for more information on the +meaning of trust settings. + +Future versions of OpenSSL will recognise trust settings on any +certificate: not just root CAs. + + +=over 4 + +=item B<-trustout> + +this causes B to output a B certificate. An ordinary +or trusted certificate can be input but by default an ordinary +certificate is output and any trust settings are discarded. With the +B<-trustout> option a trusted certificate is output. A trusted +certificate is automatically output if any trust settings are modified. + +=item B<-setalias arg> + +sets the alias of the certificate. This will allow the certificate +to be referred to using a nickname for example "Steve's Certificate". + +=item B<-alias> + +outputs the certificate alias, if any. + +=item B<-clrtrust> + +clears all the permitted or trusted uses of the certificate. + +=item B<-clrreject> + +clears all the prohibited or rejected uses of the certificate. + +=item B<-addtrust arg> + +adds a trusted certificate use. Currently acceptable values +are B (any purpose), B (SSL client use), B +(SSL server use) B (S/MIME email) and B (Object signing). + +=item B<-addreject arg> + +adds a prohibited use. It accepts the same values as the B<-addtrust> +option. + +=item B<-purpose> + +this option performs tests on the certificate extensions and outputs +the results. For a more complete description see the B section. + +=back + +=head1 SIGNING OPTIONS + +The B utility can be used to sign certificates and requests: it +can thus behave like a "mini CA". + +=over 4 + +=item B<-signkey filename> + +this option causes the input file to be self signed using the supplied +private key. + +If the input file is a certificate it sets the issuer name to the +subject name (i.e. makes it self signed) changes the public key to the +supplied value and changes the start and end dates. The start date is +set to the current time and the end date is set to a value determined +by the B<-days> option. Any certificate extensions are retained unless +the B<-clrext> option is supplied. + +If the input is a certificate request then a self signed certificate +is created using the supplied private key using the subject name in +the request. + +=item B<-clrext> + +delete any extensions from a certificate. This option is used when a +certificate is being created from another certificate (for example with +the B<-signkey> or the B<-CA> options). Normally all extensions are +retained. + +=item B<-keyform PEM|DER> + +specifies the format (DER or PEM) of the private key file used in the +B<-signkey> option. + +=item B<-days arg> + +specifies the number of days to make a certificate valid for. The default +is 30 days. + +=item B<-x509toreq> + +converts a certificate into a certificate request. The B<-signkey> option +is used to pass the required private key. + +=item B<-req> + +by default a certificate is expected on input. With this option a +certificate request is expected instead. + +=item B<-CA filename> + +specifies the CA certificate to be used for signing. When this option is +present B behaves like a "mini CA". The input file is signed by this +CA using this option: that is its issuer name is set to the subject name +of the CA and it is digitally signed using the CAs private key. + +This option is normally combined with the B<-req> option. Without the +B<-req> option the input is a certificate which must be self signed. + +=item B<-CAkey filename> + +sets the CA private key to sign a certificate with. If this option is +not specified then it is assumed that the CA private key is present in +the CA certificate file. + +=item B<-CAserial filename> + +sets the CA serial number file to use. + +When the B<-CA> option is used to sign a certificate it uses a serial +number specified in a file. This file consist of one line containing +an even number of hex digits with the serial number to use. After each +use the serial number is incremented and written out to the file again. + +The default filename consists of the CA certificate file base name with +".srl" appended. For example if the CA certificate file is called +"mycacert.pem" it expects to find a serial number file called "mycacert.srl". + +=item B<-CAcreateserial filename> + +with this option the CA serial number file is created if it does not exist: +it will contain the serial number "01". Normally if the B<-CA> option is +specified and the serial number file does not exist it is an error. + +=item B<-extfile filename> + +file containing certificate extensions to use. If not specified then +no extensions are added to the certificate. + +=item B<-extensions section> + +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. + +=back + +=head1 EXAMPLES + +Note: in these examples the '\' means the example should be all on one +line. + +Display the contents of a certificate: + + openssl x509 -in cert.pem -noout -text + +Display the certificate serial number: + + openssl x509 -in cert.pem -noout -serial + +Display the certificate MD5 fingerprint: + + openssl x509 -in cert.pem -noout -fingerprint + +Display the certificate SHA1 fingerprint: + + openssl x509 -sha1 -in cert.pem -noout -fingerprint + +Convert a certificate from PEM to DER format: + + openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER + +Convert a certificate to a certificate request: + + openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem + +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 \ + -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 \ + -CA cacert.pem -CAkey key.pem -CAcreateserial + + +Set a certificate to be trusted for SSL client use and change set its alias to +"Steve's Class 1 CA" + + openssl x509 -in cert.pem -addtrust sslclient \ + -alias "Steve's Class 1 CA" -out trust.pem + +=head1 NOTES + +The PEM format uses the header and footer lines: + + -----BEGIN CERTIFICATE---- + -----END CERTIFICATE---- + +it will also handle files containing: + + -----BEGIN X509 CERTIFICATE---- + -----END X509 CERTIFICATE---- + +Trusted certificates have the lines + + -----BEGIN TRUSTED CERTIFICATE---- + -----END TRUSTED CERTIFICATE---- + +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 +two certificates with the same fingerprint can be considered to be the same. + +The Netscape fingerprint uses MD5 whereas MSIE uses SHA1. + +=head1 CERTIFICATE EXTENSIONS + +The B<-purpose> option checks the certificate extensions and determines +what the certificate can be used for. The actual checks done are rather +complex and include various hacks and workarounds to handle broken +certificates and software. + +The same code is used when verifying untrusted certificates in chains +so this section is useful if a chain is rejected by the verify code. + +The basicConstraints extension CA flag is used to determine whether the +certificate can be used as a CA. If the CA flag is true then it is a CA, +if the CA flag is false then it is not a CA. B CAs should have the +CA flag set to true. + +If the basicConstraints extension is absent then the certificate is +considered to be a "possible CA" other extensions are checked according +to the intended use of the certificate. A warning is given in this case +because the certificate should really not be regarded as a CA: however +it is allowed to be a CA to work around some broken software. + +If the certificate is a V1 certificate (and thus has no extensions) and +it is self signed it is also assumed to be a CA but a warning is again +given: this is to work around the problem of Verisign roots which are V1 +self signed certificates. + +If the keyUsage extension is present then additional restraints are +made on the uses of the certificate. A CA certificate B have the +keyCertSign bit set if the keyUsage extension is present. + +The extended key usage extension places additional restrictions on the +certificate uses. If this extension is present (whether critical or not) +the key can only be used for the purposes specified. + +A complete description of each test is given below. The comments about +basicConstraints and keyUsage and V1 certificates above apply to B +CA certificates. + + +=over 4 + +=item B + +The extended key usage extension must be absent or include the "web client +authentication" OID. keyUsage must be absent or it must have the +digitalSignature bit set. Netscape certificate type must be absent or it must +have the SSL client bit set. + +=item B + +The extended key usage extension must be absent or include the "web client +authentication" OID. Netscape certificate type must be absent or it must have +the SSL CA bit set: this is used as a work around if the basicConstraints +extension is absent. + +=item B + +The extended key usage extension must be absent or include the "web server +authentication" and/or one of the SGC OIDs. keyUsage must be absent or it +must have the digitalSignature, the keyEncipherment set or both bits set. +Netscape certificate type must be absent or have the SSL server bit set. + +=item B + +The extended key usage extension must be absent or include the "web server +authentication" and/or one of the SGC OIDs. Netscape certificate type must +be absent or the SSL CA bit must be set: this is used as a work around if the +basicConstraints extension is absent. + +=item B + +For Netscape SSL clients to connect to an SSL server it must have the +keyEncipherment bit set if the keyUsage extension is present. This isn't +always valid because some cipher suites use the key for digital signing. +Otherwise it is the same as a normal SSL server. + +=item B + +The extended key usage extension must be absent or include the "email +protection" OID. Netscape certificate type must be absent or should have the +S/MIME bit set. If the S/MIME bit is not set in netscape certificate type +then the SSL client bit is tolerated as an alternative but a warning is shown: +this is because some Verisign certificates don't set the S/MIME bit. + +=item B + +In addition to the common S/MIME client tests the digitalSignature bit must +be set if the keyUsage extension is present. + +=item B + +In addition to the common S/MIME tests the keyEncipherment bit must be set +if the keyUsage extension is present. + +=item B + +The extended key usage extension must be absent or include the "email +protection" OID. Netscape certificate type must be absent or must have the +S/MIME CA bit set: this is used as a work around if the basicConstraints +extension is absent. + +=item B + +The keyUsage extension must be absent or it must have the CRL signing bit +set. + +=item B + +The normal CA tests apply. Except in this case the basicConstraints extension +must be present. + +=back + +=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. + +It is possible to produce invalid certificates or requests by specifying the +wrong private key or using inconsistent options in some cases: these should +be checked. + +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 +is currently being developed. It thus describes the intended behavior rather +than the current behaviour. It is hoped that it will represent reality in +OpenSSL 0.9.5 and later. + +=head1 SEE ALSO + +req(1), ca(1), genrsa(1), gendsa(1), verify(1) + +=cut diff --git a/doc/man/README b/doc/man/README deleted file mode 100644 index c63598adc3..0000000000 --- a/doc/man/README +++ /dev/null @@ -1,11 +0,0 @@ -This is *very* preliminary documentation for some -of the main commands in the openssl utility. The -information reflects the way the commands may work -when OpenSSL 0.9.5 is released. They are subject -to change though. - -The stuff is in POD format and has just been tested -with pod2man where is looks passable. It may well -look odd in html or other formats. Feel free to tidy -up, reformat or convert to a completely different -format if so desired... diff --git a/doc/man/asn1parse.pod b/doc/man/asn1parse.pod deleted file mode 100644 index e76e9813ab..0000000000 --- a/doc/man/asn1parse.pod +++ /dev/null @@ -1,129 +0,0 @@ -=pod - -=head1 NAME - -asn1parse - ASN.1 parsing tool - -=head1 SYNOPSIS - -B B -[B<-inform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-offset number>] -[B<-length number>] -[B<-i>] -[B<-oid filename>] -[B<-strparse offset>] - -=head1 DESCRIPTION - -The B command is a diagnostic utility that can parse ASN.1 -structures. It can also be used to extract data from ASN.1 formatted data. - -=head1 OPTIONS - -=over 4 - -=item B<-inform> B - -the input format. B is binary format and B (the default) is base64 -encoded. - -=item B<-in filename> - -the input file, default is standard input - -=item B<-out filename> - -output file to place the DER encoded data into. If this -option is not present then no data will be output. This is most useful when -combined with the B<-strparse> option. - -=item B<-noout> - -don't output the parsed version of the input file. - -=item B<-offset number> - -starting offset to begin parsing, default is start of file. - -=item B<-length number> - -number of bytes to parse, default is until end of file. - -=item B<-i> - -indents the output according to the "depth" of the structures. - -=item B<-oid filename> - -a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this -file is described in the NOTES section below. - -=item B<-strparse offset> - -parse the contents octets of the ASN.1 object starting at B. This -option can be used multiple times to "drill down" into a nested structure. - - -=back - -=head2 OUTPUT - -The output will typically contain lines like this: - - 0:d=0 hl=4 l= 681 cons: SEQUENCE - -..... - - 229:d=3 hl=3 l= 141 prim: BIT STRING - 373:d=2 hl=3 l= 162 cons: cont [ 3 ] - 376:d=3 hl=3 l= 159 cons: SEQUENCE - 379:d=4 hl=2 l= 29 cons: SEQUENCE - 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier - 386:d=5 hl=2 l= 22 prim: OCTET STRING - 410:d=4 hl=2 l= 112 cons: SEQUENCE - 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier - 417:d=5 hl=2 l= 105 prim: OCTET STRING - 524:d=4 hl=2 l= 12 cons: SEQUENCE - -..... - -This example is part of a self signed certificate. Each line starts with the -offset in decimal. B specifies the current depth. The depth is increased -within the scope of any SET or SEQUENCE. B gives the header length -(tag and length octets) of the current type. B gives the length of -the contents octets. - -The B<-i> option can be used to make the output more readable. - -Some knowledge of the ASN.1 structure is needed to interpret the output. - -In this example the BIT STRING at offset 229 is the certificate public key. -The contents octets of this will contain the public key information. This can -be examined using the option B<-strparse 229> to yield: - - 0:d=0 hl=3 l= 137 cons: SEQUENCE - 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897 - 135:d=1 hl=2 l= 3 prim: INTEGER :010001 - -=head1 NOTES - -If an OID is not part of OpenSSL's internal table it will be represented in -numerical form (for example 1.2.3.4). The file passed to the B<-oid> option -allows additional OIDs to be included. Each line consists of three columns, -the first column is the OID in numerical format and should be followed by white -space. The second column is the "short name" which is a single word followed -by white space. The final column is the rest of the line and is the -"long name". B displays the long name. Example: - -C<1.2.3.4 shortName A long name> - -=head1 BUGS - -There should be options to change the format of input lines. The output of some -ASN.1 types is not well handled (if at all). - -=cut diff --git a/doc/man/ca.pod b/doc/man/ca.pod deleted file mode 100644 index 999622b570..0000000000 --- a/doc/man/ca.pod +++ /dev/null @@ -1,472 +0,0 @@ - -=pod - -=head1 NAME - -ca - sample minimal CA application - -=head1 SYNOPSIS - -B B -[B<-verbose>] -[B<-config filename>] -[B<-name section>] -[B<-gencrl>] -[B<-revoke file>] -[B<-crldays days>] -[B<-crlhours hours>] -[B<-crlexts section>] -[B<-startdate date>] -[B<-enddate date>] -[B<-days arg>] -[B<-md arg>] -[B<-policy arg>] -[B<-keyfile arg>] -[B<-key arg>] -[B<-cert file>] -[B<-in file>] -[B<-out file>] -[B<-outdir dir>] -[B<-infiles>] -[B<-spkac file>] -[B<-ss_cert file>] -[B<-preserveDN>] -[B<-batch>] -[B<-msie_hack>] -[B<-extensions section>] - -=head1 DESCRIPTION - -The B command is a minimal CA application. It can be used -to sign certificate requests in a variety of forms and generate -CRLs it also maintains a text database of issued certificates -and their status. - -The options descriptions will be divided into each purpose. - -=head1 CA OPTIONS - -=over 4 - -=item B<-config filename> - -specifies the configuration file to use. - -=item B<-in filename> - -an input filename containing a single certificate request to be -signed by the CA. - -=item B<-ss_cert filename> - -a single self signed certificate to be signed by the CA. - -=item B<-spkac filename> - -a file containing a single Netscape signed public key and challenge -and additional field values to be signed by the CA. See the B -section for information on the required format. - -=item B<-infiles> - -if present this should be the last option, all subsequent arguments -are assumed to the the names of files containing certificate requests. - -=item B<-out filename> - -the output file to output certificates to. The default is standard -output. The certificate details will also be printed out to this -file. - -=item B<-outdir directory> - -the directory to output certificates to. The certificate will be -written to a filename consisting of the serial number in hex with -".pem" appended. - -=item B<-cert> - -the CA certificate file. - -=item B<-keyfile filename> - -the private key to sign requests with. - -=item B<-key password> - -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<-verbose> - -this prints extra details about the operations being performed. - -=item B<-startdate date> - -this allows the start date to be explicitly set. The format of the -date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). - -=item B<-enddate date> - -this allows the expiry date to be explicitly set. The format of the -date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). - -=item B<-days arg> - -the number of days to certify the certificate for. - -=item B<-md alg> - -the message digest to use. Possible values include md5, sha1 and mdc2. -This option also applies to CRLs. - -=item B<-policy arg> - -this option defines the CA "policy" to use. This is a section in -the configuration file which decides which fields should be mandatory -or match the CA certificate. Check out the B section -for more information. - -=item B<-msie_hack> - -this is a legacy option to make B work with very old versions of -the IE certificate enrollment control "certenr3". It used UniversalStrings -for almost everything. Since the old control has various security bugs -its use is strongly discouraged. The newer control "Xenroll" does not -need this option. - -=item B<-preserveDN> - -Normally the DN order of a certificate is the same as the order of the -fields in the relevant policy section. When this option is set the order -is the same as the request. This is largely for compatibility with the -older IE enrollment control which would only accept certificates if their -DNs match the order of the request. This is not needed for Xenroll. - -=item B<-batch> - -this sets the batch mode. In this mode no questions will be asked -and all certificates will be certified automatically. - -=item B<-extensions section> - -the section of the configuration file containing certificate extensions -to be added when a certificate is issued. 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. - -=back - -=head1 CRL OPTIONS - -=over 4 - -=item B<-gencrl> - -this option generates a CRL based on information in the index file. - -=item B<-crldays num> - -the number of days before the next CRL is due. That is the days from -now to place in the CRL nextUpdate field. - -=item B<-crlhours num> - -the number of hours before the next CRL is due. - -=item B<-revoke filename> - -a filename containing a certificate to revoke. - -=item B<-crlexts section> - -the section of the configuration file containing CRL extensions to -include. If no CRL extension section is present then a V1 CRL is -created, if the CRL extension section is present (even if it is -empty) then a V2 CRL is created. The CRL extensions specified are -CRL extensions and B CRL entry extensions. It should be noted -that some software (for example Netscape) can't handle V2 CRLs. - -=back - -=head1 CONFIGURATION FILE OPTIONS - -The options for B are contained in the B section of the -configuration file. Many of these are identical to command line -options. Where the option is present in the configuration file -and the command line the command line value is used. Where an -option is described as mandatory then it must be present in -the configuration file or the command line equivalent (if -any) used. - -=over 4 - -=item B - -This specifies a file containing additional B. -Each line of the file should consist of the numerical form of the -object identifier followed by white space then the short name followed -by white space and finally the long name. - -=item B - -This specifies a section in the configuration file containing extra -object identifiers. Each line should consist of the short name of the -object identifier followed by B<=> and the numerical form. The short -and long names are the same when this option is used. - -=item B - -the same as the B<-outdir> command line option. It specifies -the directory where new certificates will be placed. Mandatory. - -=item B - -the same as B<-cert>. It gives the file containing the CA -certificate. Mandatory. - -=item B - -same as the B<-keyfile> option. The file containing the -CA private key. Mandatory. - -=item B - -a file used to read and write random number seed information. - -=item B - -the same as the B<-days> option. The number of days to certify -a certificate for. - -=item B - -the same as the B<-startdate> option. The start date to certify -a certificate for. If not set the current time is used. - -=item B - -the same as the B<-enddate> option. Either this option or -B (or the command line equivalents) must be -present. - -=item B - -the same as the B<-crlhours> and the B<-crldays> options. These -will only be used if neither command line option is present. At -least one of these must be present to generate a CRL. - -=item B - -the same as the B<-md> option. The message digest to use. Mandatory. - -=item B - -the text database file to use. Mandatory. This file must be present -though initially it will be empty. - -=item B - -a text file containing the next serial number to use in hex. Mandatory. -This file must be present and contain a valid serial number. - -=item B - -the same as B<-extensions>. - -=item B - -the same as B<-crlexts>. - -=item B - -the same as B<-preserveDN> - -=item B - -the same as B<-msie_hack> - -=item B - -the same as B<-policy>. Mandatory. See the B section -for more information. - -=back - -=head1 POLICY FORMAT - -The policy section consists of a set of variables corresponding to -certificate DN fields. If the value is "match" then the field value -must match the same field in the CA certificate. If the value is -"supplied" then it must be present. If the value is "optional" then -it may be present. Any fields not mentioned in the policy section -are silently deleted, unless the B<-preserveDN> option is set but -this can be regarded more of a quirk than intended behaviour. - -=head1 SPKAC FORMAT - -The input to the B<-spkac> command line option is a Netscape -signed public key and challenge. This will usually come from -the B tag in an HTML form to create a new private key. -It is however possible to create SPKACs using the B utility. - -The file should contain the variable SPKAC set to the value of -the SPKAC and also the required DN components as name value pairs. -If you need to include the same component twice then it can be -preceded by a number and a '.'. - -=head1 EXAMPLES - -Note: these examples assume that the B directory structure is -already set up and the relevant files already exist. This usually -involves creating a CA certificate and private key with B, a -serial number file and an empty index file and placing them in -the relevant directories. - -To use the sample configuration file below the directories demoCA, -demoCA/private and demoCA/newcerts would be created. The CA -certificate would be copied to demoCA/cacert.pem and its private -key to demoCA/private/cakey.pem. A file demoCA/serial would be -created containing for example "01" and the empty index file -demoCA/index.txt. - - -Sign a certificate request: - -openssl ca -in req.pem -out newcert.pem - -Generate a CRL - -openssl ca -gencrl -out crl.pem - -Sign several requests: - -openssl ca -infiles req1.pem req2.pem req3.pem - -Certify a Netscape SPKAC: - -openssl ca -spkac spkac.txt - -A sample SPKAC file (the SPKAC line has been truncated for clarity): - - SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 - CN=Steve Test - emailAddress=steve@openssl.org - 0.OU=OpenSSL Group - 1.OU=Another Group - -A sample configuration file with the relevant sections for B: - - [ ca ] - default_ca = CA_default # The default ca section - - [ CA_default ] - - dir = ./demoCA # top dir - database = $dir/index.txt # index file. - new_certs_dir = $dir/newcerts # new certs dir - - certificate = $dir/cacert.pem # The CA cert - serial = $dir/serial # serial no file - private_key = $dir/private/cakey.pem# CA private key - RANDFILE = $dir/private/.rand # random number file - - default_days = 365 # how long to certify for - default_crl_days= 30 # how long before next CRL - default_md = md5 # md to use - - policy = policy_any # default policy - - [ policy_any ] - countryName = supplied - stateOrProvinceName = optional - organizationName = optional - organizationalUnitName = optional - commonName = supplied - emailAddress = optional - -=head1 WARNINGS - -The B command is quirky and at times downright unfriendly. - -The B utility was originally meant as an example of how to do things -in a CA. It was not supposed be be used as a full blown CA itself: -nevertheless some people are using it for this purpose. - -The B command is effectively a single user command: no locking is -done on the various files and attempts to run more than one B command -on the same database can have unpredictable results. - -=head1 FILES - -Note: the location of all files can change either by compile time options, -configuration file entries, environment variables or command line options. -The values below reflect the default values. - - /usr/local/ssl/lib/openssl.cnf - master configuration file - ./demoCA - main CA directory - ./demoCA/cacert.pem - CA certificate - ./demoCA/private/cakey.pem - CA private key - ./demoCA/serial - CA serial number file - ./demoCA/serial.old - CA serial number backup file - ./demoCA/index.txt - CA text database file - ./demoCA/index.txt.old - CA text database backup file - ./demoCA/certs - certificate output file - ./demoCA/.rnd - CA random seed information - -=head1 ENVIRONMENT VARIABLES - -B reflects the location of master configuration file it can -be overridden by the B<-config> command line option. - -=head1 RESTRICTIONS - -The text database index file is a critical part of the process and -if corrupted it can be difficult to fix. It is theoretically possible -to rebuild the index file from all the issued certificates and a current -CRL: however there is no option to do this. - -CRL entry extensions cannot currently be created: only CRL extensions -can be added. - -V2 CRL features like delta CRL support and CRL numbers are not currently -supported. - -Although several requests can be input and handled at once it is only -possible to include one SPKAC or self signed certificate. - -=head1 BUGS - -The use of an in memory text database can cause problems when large -numbers of certificates are present because, as the name implies -the database has to be kept in memory. - -Certificate request extensions are ignored: some kind of "policy" should -be included to use certain static extensions and certain extensions -from the request. - -It is not possible to certify two certificates with the same DN: this -is a side effect of how the text database is indexed and it cannot easily -be fixed without introducing other problems. Some S/MIME clients can use -two certificates with the same DN for separate signing and encryption -keys. - -The B command really needs rewriting or the required functionality -exposed at either a command or interface level so a more friendly utility -(perl script or GUI) can handle things properly. The scripts B and -B help a little but not very much. - -Any fields in a request that are not present in a policy are silently -deleted. This does not happen if the B<-preserveDN> option is used but -the extra fields are not displayed when the user is asked to certify -a request. The behaviour should be more friendly and configurable. - -Cancelling some commands by refusing to certify a certificate can -create an empty file. - -=head1 SEE ALSO - -req(1), spkac(1), x509(1), CA.pl(1), config(5) - -=cut diff --git a/doc/man/config.pod b/doc/man/config.pod deleted file mode 100644 index a5974d945a..0000000000 --- a/doc/man/config.pod +++ /dev/null @@ -1,138 +0,0 @@ - -=pod - -=head1 NAME - -config - OpenSSL CONF library configuration files - -=head1 DESCRIPTION - -The OpenSSL CONF library can be used to read configuration files. -It is used for the OpenSSL master configuration file B -and in a few other places like B files and certificate extension -files for the B utility. - -A configuration file is divided into a number of sections. Each section -starts with a line B<[ section_name ]> and ends when a new section is -started or end of file is reached. A section name can consist of -alphanumeric characters and underscores. - -The first section of a configuration file is special and is referred -to as the B section this is usually unnamed and is from the -start of file until the first named section. When a name is being looked up -it is first looked up in a named section (if any) and then the -default section. - -The environment is mapped onto a section called B. - -Comments can be included by preceding them with the B<#> character - -Each section in a configuration file consists of a number of name and -value pairs of the form B - -The B string can contain any alphanumeric characters as well as -a few punctuation symbols such as B<.> B<,> B<;> and B<_>. - -The B string consists of the string following the B<=> character -until end of line with any leading and trailing white space removed. - -The value string undergoes variable expansion. This can be done by -including the form B<$var> or B<${var}>: this will substitute the value -of the named variable in the current section. It is also possible to -substitute a value from another section using the syntax B<$section::name> -or B<${section::name}>. By using the form B<$ENV::name> environment -variables can be substituted. It is also possible to assign values to -environment variables by using the name B, this will work -if the program looks up environment variables using the B library -instead of calling B directly. - -It is possible to escape certain characters by using any kind of quote -or the B<\> character. By making the last character of a line a B<\> -a B string can be spread across multiple lines. In addition -the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognised. - -=head1 NOTES - -If a configuration file attempts to expand a variable that doesn't exist -then an error is flagged and the file will not load. This can happen -if an attempt is made to expand an environment variable that doesn't -exist. For example the default OpenSSL master configuration file used -the value of B which may not be defined on non Unix systems. - -This can be worked around by including a B section to provide -a default value: then if the environment lookup fails the default value -will be used instead. For this to work properly the default value must -be defined earlier in the configuration file than the expansion. See -the B section for an example of how to do this. - -If the same variable exists in the same section then all but the last -value will be silently ignored. In certain circumstances such as with -DNs the same field may occur multiple times. This is usually worked -around by ignoring any characters before an initial B<.> e.g. - - 1.OU="My first OU" - 2.OU="My Second OU" - -=head1 EXAMPLES - -Here is a sample configuration file using some of the features -mentioned above. - - # This is the default section. - - HOME=/temp - RANDFILE= ${ENV::HOME}/.rnd - configdir=$ENV::HOME/config - - [ section_one ] - - # We are now in section one. - - # Quotes permit leading and trailing whitespace - any = " any variable name " - - other = A string that can \ - cover several lines \ - by including \\ characters - - message = Hello World\n - - [ section_two ] - - greeting = $section_one::message - -This next example shows how to expand environment variables safely. - -Suppose you want a variable called B to refer to a -temporary filename. The directory it is placed in can determined by -the the B or B environment variables but they may not be -set to any value at all. If you just include the environment variable -names and the variable doesn't exist then this will cause an error when -an attempt is made to load the configuration file. By making use of the -default section both values can be looked up with B taking -priority and B used if neither is defined: - - TMP=/tmp - # The above value is used if TMP isn't in the environment - TEMP=$ENV::TMP - # The above value is used if TEMP isn't in the environment - tmpfile=${ENV::TEMP}/tmp.filename - -=head1 BUGS - -Currently there is no way to include characters using the octal B<\nnn> -form. Strings are all null terminated so nulls cannot form part of -the value. - -The escaping isn't quite right: if you want to use sequences like B<\n> -you can't use any quote escaping on the same line. - -Files are loaded in a single pass. This means that an variable expansion -will only work if the variables referenced are defined earlier in the -file. - -=head1 SEE ALSO - -x509(1), req(1), ca(1) - -=cut diff --git a/doc/man/crl.pod b/doc/man/crl.pod deleted file mode 100644 index 8b19592c85..0000000000 --- a/doc/man/crl.pod +++ /dev/null @@ -1,110 +0,0 @@ -=pod - -=head1 NAME - -crl - CRL utility - -=head1 SYNOPSIS - -B B -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-text>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-hash>] -[B<-issuer>] -[B<-lastupdate>] -[B<-nextupdate>] -[B<-CAfile file>] -[B<-CApath dir>] - -=head1 DESCRIPTION - -The B command processes CRL files in DER or PEM format. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. B format is DER encoded CRL -structure. B (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=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 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<-text> - -print out the CRL in text form. - -=item B<-noout> - -don't output the encoded version of the CRL. - -=item B<-hash> - -output a hash of the issuer name. This can be use to lookup CRLs in -a directory by issuer name. - -=item B<-issuer> - -output the issuer name. - -=item B<-lastupdate> - -output the lastUpdate field. - -=item B<-nextupdate> - -output the nextUpdate field. - -=item B<-CAfile file> - -verify the signature on a CRL by looking up the issuing certificate in -B - -=item B<-CApath dir> - -verify the signature on a CRL by looking up the issuing certificate in -B. This directory must be a standard certificate directory: that -is a hash of each subject name (using B) should be linked -to each certificate. - -=back - -=head1 EXAMPLES - -Convert a CRL file from PEM to DER: - - openssl crl -in crl.pem -outform DER -out crl.der - -Output the text form of a DER encoded certificate: - - openssl crl -in crl.der -text -noout - -=head1 BUGS - -Ideally it should be possible to create a CRL using appropriate options -and files too. - -=head1 SEE ALSO - -crl2pkcs7(1), ca(1), x509(1) - -=cut diff --git a/doc/man/crl2pkcs7.pod b/doc/man/crl2pkcs7.pod deleted file mode 100644 index ad749ed0c3..0000000000 --- a/doc/man/crl2pkcs7.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=head1 NAME - -crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates. - -=head1 SYNOPSIS - -B B -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-print_certs>] - -=head1 DESCRIPTION - -The B command takes an optional CRL and one or more -certificates and converts them into a PKCS#7 degenerate "certificates -only" structure. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the CRL input format. B format is DER encoded CRL -structure.B (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the PKCS#7 structure output format. B format is DER -encoded PKCS#7 structure.B (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=item B<-in filename> - -This specifies the input filename to read a CRL from or standard input if this -option is not specified. - -=item B<-out filename> - -specifies the output filename to write the PKCS#7 structure to or standard -output by default. - -=item B<-certfile filename> - -specifies a filename containing one or more certificates in B format. -All certificates in the file will be added to the PKCS#7 structure. This -option can be used more than once to read certificates form multiple -files. - -=item B<-nocrl> - -normally a CRL is included in the output file. With this option no CRL is -included in the output file and a CRL is not read from the input file. - -=back - -=head1 EXAMPLES - -Create a PKCS#7 structure from a certificate and CRL: - - openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem - -Creates a PKCS#7 structure in DER format with no CRL from several -different certificates: - - openssl crl2pkcs7 -nocrl -certfile newcert.pem - -certfile demoCA/cacert.pem -outform DER -out p7.der - -=head1 NOTES - -The output file is a PKCS#7 signed data structure containing no signers and -just certificates and an optional CRL. - -This utility can be used to send certificates and CAs to Netscape as part of -the certificate enrollment process. This involves sending the DER encoded output -as MIME type application/x-x509-user-cert. - -The B encoded form with the header and footer lines removed can be used to -install user certificates and CAs in MSIE using the Xenroll control. - -=head1 SEE ALSO - -pkcs7(1) - -=cut diff --git a/doc/man/dgst.pod b/doc/man/dgst.pod deleted file mode 100644 index cbf2cc529a..0000000000 --- a/doc/man/dgst.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - -dgst, md5, md2, sha1, sha, mdc2, ripemd160 - message digests - -=head1 SYNOPSIS - -[B] -[B<-md5|-md2|-sha1|-sha|mdc2|-ripemd160>] -[B<-c>] -[B<-d>] -[B] - -[B] -[B<-c>] -[B<-d>] -[B] - -=head1 DESCRIPTION - -The digest functions print out the message digest of a supplied file or files -in hexadecimal form. - -=head1 OPTIONS - -=over 4 - -=item B<-c> - -print out the digest in two digit groups separated by colons. - -=item B<-d> - -print out BIO debugging information. - -=item B - -file or files to digest. If no files are specified then standard input is -used. - -=back - -=head1 NOTES - -The digest of choice for all new applications is SHA1. Other digests are -however still widely used. - -=cut diff --git a/doc/man/dh.pod b/doc/man/dh.pod deleted file mode 100644 index 99b307368f..0000000000 --- a/doc/man/dh.pod +++ /dev/null @@ -1,87 +0,0 @@ -=pod - -=head1 NAME - -dh - DH parameter manipulation and generation - -=head1 SYNOPSIS - -B -[B<-inform DER|PEM>] -[B<-outform DER|PEM>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-text>] -[B<-C>] - -=head1 DESCRIPTION - -This command is used to manipulate DH parameter files. - -=head1 OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B option uses an ASN1 DER encoded -form compatible with the PKCS#3 DHparameter structure. The PEM form is the -default format: it consists of the B format base64 encoded with -additional header and footer lines. - -=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 parameters from or standard input if -this option is not specified. - -=item B<-out filename> - -This specifies the output filename parameters to. Standard output is used -if this option is not present. The output filename should B be the same -as the input filename. - -=item B<-noout> - -this option inhibits the output of the encoded version of the parameters. - -=item B<-text> - -this option prints out the DH parameters in human readable form. - -=item B<-C> - -this option converts the parameters into C code. The parameters can then -be loaded by calling the B function. - -=back - -=head1 NOTES - -PEM format DH parameters use the header and footer lines: - - -----BEGIN DH PARAMETERS----- - -----END DH PARAMETERS----- - -OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42 -DH. - -This program manipulates DH parameters not keys. - -=head1 BUGS - -This program is badly named: the B and B programs manipulate keys -and not parameters. - -There should be a way to generate and manipulate DH keys. - -=head1 SEE ALSO - -dsaparam(1) - -=cut diff --git a/doc/man/dsa.pod b/doc/man/dsa.pod deleted file mode 100644 index 1235e5598b..0000000000 --- a/doc/man/dsa.pod +++ /dev/null @@ -1,154 +0,0 @@ -=pod - -=head1 NAME - -dsa - DSA key processing - -=head1 SYNOPSIS - -B B -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin password>] -[B<-envpassin var>] -[B<-out filename>] -[B<-passout password>] -[B<-envpassout var>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-text>] -[B<-noout>] -[B<-modulus>] -[B<-pubin>] -[B<-pubout>] - -=head1 DESCRIPTION - -The B command processes DSA keys. They can be converted between various -forms and their components printed out. B This command uses the -traditional SSLeay compatible format for private key encryption: newer -applications should use the more secure PKCS#8 format using the B - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B option with a private key uses -an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of -version (currently zero), p, q, g, the public and private key components -respectively as ASN.1 INTEGERs. When used with a public key it uses a -SubjectPublicKeyInfo structure: it is an error if the key is not DSA. - -The B form is the default format: it consists of the B format base64 -encoded with additional header and footer lines. In the case of a private key -PKCS#8 format is also accepted. - -=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 password> - -the input file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassin var> - -read the input file password from the environment variable B. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output by -is not specified. If any encryption options are set then a pass phrase will be -prompted for. The output filename should B be the same as the input -filename. - -=item B<-passout password> - -the output file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassout var> - -read the output file password from the environment variable B. - -=item B<-des|-des3|-idea> - -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. A pass phrase is prompted for. -If none of these options is specified the key is written in plain text. This -means that using the B utility to read in an encrypted key with no -encryption option can be used to remove the pass phrase from a key, or by -setting the encryption options it can be use to add or change the pass phrase. -These options can only be used with PEM format output files. - -=item B<-text> - -prints out the public, private key components and parameters. - -=item B<-noout> - -this option prevents output of the encoded version of the key. - -=item B<-modulus> - -this option prints out the value of the public key component of the key. - -=item B<-pubin> - -by default a private key is input file with this option a public key is input -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. - -=back - -=head1 NOTES - -The PEM private key format uses the header and footer lines: - - -----BEGIN DSA PRIVATE KEY----- - -----END DSA PRIVATE KEY----- - -=head1 EXAMPLES - -To remove the pass phrase on a DSA private key: - -C - -To encrypt a private key using triple DES: - -C - -To convert a private key from PEM to DER format: - -C - -To print out the components of a private key to standard output: - -C - -To just output the public part of a private key: - -C - -=head1 SEE ALSO - -dsaparam(1), gendsa(1), rsa(1), genrsa(1) - -=cut diff --git a/doc/man/dsaparam.pod b/doc/man/dsaparam.pod deleted file mode 100644 index f5f3f317bd..0000000000 --- a/doc/man/dsaparam.pod +++ /dev/null @@ -1,100 +0,0 @@ -=pod - -=head1 NAME - -dsaparam - DSA parameter manipulation and generation - -=head1 SYNOPSIS - -B -[B<-inform DER|PEM>] -[B<-outform DER|PEM>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-text>] -[B<-C>] -[B<-rand file(s)>] -[B<-genkey>] -[B] - -=head1 DESCRIPTION - -This command is used to manipulate or generate DSA parameter files. - -=head1 OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B option uses an ASN1 DER encoded -form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting -of p, q and g respectively. The PEM form is the default format: it consists -of the B format base64 encoded with additional header and footer lines. - -=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 parameters from or standard input if -this option is not specified. If the B parameter is included then -this option will be ignored. - -=item B<-out filename> - -This specifies the output filename parameters to. Standard output is used -if this option is not present. The output filename should B be the same -as the input filename. - -=item B<-noout> - -this option inhibits the output of the encoded version of the parameters. - -=item B<-text> - -this option prints out the DSA parameters in human readable form. - -=item B<-C> - -this option converts the parameters into C code. The parameters can then -be loaded by calling the B function. - -=item B<-genkey> - -this option will generate a DSA either using the specified or generated -parameters. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator. Multiple files can be specified separated by a OS-dependent -character. For MS-Windows, the separator is B<;>. For OpenVMS, it's -B<,>. For all others, it's B<:>. - -=item B - -this option specifies that a parameter set should be generated of size -B. It must be the last option. If this option is included then -the input file (if any) is ignored. - -=back - -=head1 NOTES - -PEM format DSA parameters use the header and footer lines: - - -----BEGIN DSA PARAMETERS----- - -----END DSA PARAMETERS----- - -DSA parameter generation is a slow process and as a result the same set of -DSA parameters is often used to generate several distinct keys. - -=head1 SEE ALSO - -gendsa(1), dsa(1), genrsa(1), rsa(1) - -=cut diff --git a/doc/man/enc.pod b/doc/man/enc.pod deleted file mode 100644 index 349fca00f8..0000000000 --- a/doc/man/enc.pod +++ /dev/null @@ -1,248 +0,0 @@ -=pod - -=head1 NAME - -enc - symmetric cipher routines - -=head1 SYNOPSIS - -B -[B<-in filename>] -[B<-out filename>] -[B<-e>] -[B<-d>] -[B<-a>] -[B<-A>] -[B<-k password>] -[B<-kfile filename>] -[B<-K key>] -[B<-iv IV>] -[B<-p>] -[B<-P>] -[B<-bufsize number>] -[B<-debug>] - -=head1 DESCRIPTION - -The symmetric cipher commands allow data to be encrypted or decrypted -using various block and stream ciphers using keys based on passwords -or explicitly provided. Base64 encoding or decoding can also be performed -either by itself or in addition to the encryption or decryption. - -=head1 OPTIONS - -=over 4 - -=item B<-in filename> - -the input filename, standard input by default. - -=item B<-out filename> - -the output filename, standard output by default. - -=item B<-salt> - -use a salt in the key derivation routines. This option should B -be used unless compatibility with previous versions of OpenSSL or SSLeay -is required. This option is only present on OpenSSL versions 0.9.5 or -above. - -=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. - -=item B<-e> - -encrypt the input data: this is the default. - -=item B<-d> - -decrypt the input data. - -=item B<-a> - -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<-A> - -if the B<-a> option is set then base64 process the data on one line. - -=item B<-k password> - -the password to derive the key from. - -=item B<-kfile filename> - -read the password to derive the key from the first line of B - -=item B<-S salt> - -the actual salt to use: this must be represented as a string comprised only -of hex digits. - -=item B<-K key> - -the actual key to use: this must be represented as a string comprised only -of hex digits. - -=item B<-iv IV> - -the actual IV to use: this must be represented as a string comprised only -of hex digits. - -=item B<-p> - -print out the key and IV used. - -=item B<-P> - -print out the key and IV used then immediately exit: don't do any encryption -or decryption. - -=item B<-bufsize number> - -set the buffer size for I/O - -=item B<-debug> - -debug the BIOs used for I/O. - -=back - -=head1 NOTES - -The program can be called either as B or -B. - -A password will be prompted for to derive the key and IV if necessary. - -The B<-salt> option should B be used if the key is being derived -from a password unless you want compatibility with previous versions of -OpenSSL and SSLeay. - -Without the B<-salt> option it is possible to perform efficient dictionary -attacks on the password and to attack stream cipher encrypted data. The reason -for this is that without the salt the same password always generates the same -encryption key. When the salt is being used the first eight bytes of the -encrypted data are reserved for the salt: it is generated at random when -encrypting a file and read from the encrypted file when it is decrypted. - -Some of the ciphers do not have large keys and others have security -implications if not used correctly. A beginner is advised to just use -a strong block cipher in CBC mode such as bf or des3. - -All the block ciphers use PKCS#5 padding also known as standard block -padding: this allows a rudimentary integrity or password check to be -performed. However since the chance of random data passing the test is -better than 1 in 256 it isn't a very good test. - -All RC2 ciphers have the same key and effective key length. - -Blowfish and RC5 algorithms use a 128 bit key. - -=head1 SUPPORTED CIPHERS - - base64 Base 64 - - bf-cbc Blowfish in CBC mode - bf Alias for bf-cbc - bf-cfb Blowfish in CFB mode - bf-ecb Blowfish in ECB mode - bf-ofb Blowfish in OFB mode - - cast-cbc CAST in CBC mode - cast Alias for cast-cbc - cast5-cbc CAST5 in CBC mode - cast5-cfb CAST5 in CFB mode - cast5-ecb CAST5 in ECB mode - cast5-ofb CAST5 in OFB mode - - des-cbc DES in CBC mode - des Alias for des-cbc - des-cfb DES in CBC mode - des-ofb DES in OFB mode - des-ecb DES in ECB mode - - des-ede-cbc Two key triple DES EDE in CBC mode - des-ede Alias for des-ede - des-ede-cfb Two key triple DES EDE in CFB mode - des-ede-ofb Two key triple DES EDE in OFB mode - - des-ede3-cbc Three key triple DES EDE in CBC mode - des-ede3 Alias for des-ede3-cbc - des3 Alias for des-ede3-cbc - des-ede3-cfb Three key triple DES EDE CFB mode - des-ede3-ofb Three key triple DES EDE in OFB mode - - desx DESX algorithm. - - idea-cbc IDEA algorithm in CBC mode - idea same as idea-cbc - idea-cfb IDEA in CFB mode - idea-ecb IDEA in ECB mode - idea-ofb IDEA in OFB mode - - rc2-cbc 128 bit RC2 in CBC mode - rc2 Alias for rc2-cbc - rc2-cfb 128 bit RC2 in CBC mode - rc2-ecb 128 bit RC2 in CBC mode - rc2-ofb 128 bit RC2 in CBC mode - rc2-64-cbc 64 bit RC2 in CBC mode - rc2-40-cbc 40 bit RC2 in CBC mode - - rc4 128 bit RC4 - rc4-64 64 bit RC4 - rc4-40 40 bit RC4 - - rc5-cbc RC5 cipher in CBC mode - rc5 Alias for rc5-cbc - rc5-cfb RC5 cipher in CBC mode - rc5-ecb RC5 cipher in CBC mode - rc5-ofb RC5 cipher in CBC mode - -=head1 EXAMPLES - -Just base64 encode a binary file: - - openssl base64 -in file.bin -out file.b64 - -Decode the same file - - openssl base64 -d -in file.b64 -out file.bin - -Encrypt a file using triple DES in CBC mode using a prompted password: - - openssl des3 -salt -in file.txt -out file.des3 - -Decrypt a file using a supplied password: - - openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword - -Encrypt a file then base64 encode it (so it can be sent via mail for example) -using Blowfish in CBC mode: - - openssl bf -a -salt -in file.txt -out file.bf - -Base64 decode a file then decrypt it: - - openssl bf -d -salt -a -in file.bf -out file.txt - -Decrypt some data using a supplied 40 bit RC4 key: - - openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 - -=head1 BUGS - -The B<-A> option when used with large files doesn't work properly. - -There should be an option to allow an iteration count to be included. - -Like the EVP library the B program only supports a fixed number of -algorithms with certain parameters. So if, for example, you want to use RC2 -with a 76 bit key or RC4 with an 84 bit key you can't use this program. - -=cut diff --git a/doc/man/gendh.pod b/doc/man/gendh.pod deleted file mode 100644 index 8262622a3d..0000000000 --- a/doc/man/gendh.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -gendh - DH parameter generation - -=head1 SYNOPSIS - -B -[B<-out filename>] -[B<-2>] -[B<-5>] -[B<-rand file(s)>] -[numbits] - -=head1 DESCRIPTION - -This command is used to generate DH parameter files. - -=head1 OPTIONS - -=over 4 - -=item B<-out filename> - -This specifies the output filename parameters to. Standard output is used -if this option is not present. The output format is a base64 encoded form of -a PKCS#5 DHParameter structure. - -=item B<-2>, B<-5> - -The generator to use, either 2 or 5. 2 is the default. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator. Multiple files can be specified separated by a OS-dependent -character. For MS-Windows, the separator is B<;>. For OpenVMS, it's -B<,>. For all others, it's B<:>. - -=item B - -this option specifies that a parameter set should be generated of size -B. It must be the last option. If not present then a value of 512 -is used. - -=back - -=head1 NOTES - -PEM format DH parameters use the header and footer lines: - - -----BEGIN DH PARAMETERS----- - -----END DH PARAMETERS----- - -DH parameter generation is a slow process and as a result the same set of -DH parameters is often reused. - -OpenSSL currently uses PKCS#3 DH not the more recent X9.42 DH. - -This program creates DH parameters only, not DH keys. - -=head1 BUGS - -The program is badly named. The programs B and B generate -actual keys and not parameters. - -There should be a way to generate and manipulate DH keys. - -=head1 SEE ALSO - -dsaparam(1) - -=cut diff --git a/doc/man/gendsa.pod b/doc/man/gendsa.pod deleted file mode 100644 index a23e755fa8..0000000000 --- a/doc/man/gendsa.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -gendsa - generate a DSA private key from a set of parameters - -=head1 SYNOPSIS - -B B -[B<-out filename>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-rand file(s)>] -[B] - -=head1 DESCRIPTION - -The B command generates a DSA private key from a DSA parameter file -(which will be typically generated by the B command). - -=head1 OPTIONS - -=over 4 - -=item B<-des|-des3|-idea> - -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. A pass phrase is prompted for. -If none of these options is specified no encryption is used. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator. Multiple files can be specified separated by a OS-dependent -character. For MS-Windows, the separator is B<;>. For OpenVMS, it's -B<,>. For all others, it's B<:>. - -=item B - -This option specifies the DSA parameter file to use. The parameters in this -file determine the size of the private key. DSA parameters can be generated -and examined using the B command. - -=back - -=head1 NOTES - -DSA key generation is little more than random number generation so it is -much quicker that RSA key generation for example. - -=head1 SEE ALSO - -dsaparam(1), dsa(1), genrsa(1), rsa(1) - -=cut diff --git a/doc/man/genrsa.pod b/doc/man/genrsa.pod deleted file mode 100644 index b224bd1fc8..0000000000 --- a/doc/man/genrsa.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -genrsa - generate an RSA private key - - -=head1 SYNOPSIS - -B B -[B<-out filename>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-f4>] -[B<-3>] -[B<-rand file(s)>] -[B] - -=head1 DESCRIPTION - -The B command generates an RSA private key. - -=head1 OPTIONS - -=over 4 - -=item B<-des|-des3|-idea> - -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. A pass phrase is prompted for. -If none of these options is specified no encryption is used. - -=item B<-F4|-3> - -the public exponent to use, either 65537 or 3. The default is 65537. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator. Multiple files can be specified separated by a OS-dependent -character. For MS-Windows, the separator is B<;>. For OpenVMS, it's -B<,>. For all others, it's B<:>. - -=item B - -the size of the private key to generate in bits. This must be the last option -specified. The default is 512. - -=back - -=head1 NOTES - -RSA private key generation essentially involves the generation of two prime -numbers. When generating a private key various symbols will be output to -indicate the progress of the generation. A B<.> represents each number tested. -A B<+> means a number has passed a single primality test. A newline means that -the number has passed all the prime tests (currently set to 5 single tests). - -Because key generation is a random process the time taken to generate a key -may vary somewhat. - -=head1 BUGS - -A quirk of the prime generation algorithm is that it cannot generate small -primes. Therefore the number of bits should not be less that 64. For typical -private keys this will not matter because for security reasons they will -be much larger (typically 1024 bits). - -=head1 SEE ALSO - -gendsa(1) diff --git a/doc/man/nseq.pod b/doc/man/nseq.pod deleted file mode 100644 index 989c3108fb..0000000000 --- a/doc/man/nseq.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -nseq - create or examine a netscape certificate sequence - -=head1 SYNOPSIS - -B B -[B<-in filename>] -[B<-out filename>] -[B<-toseq>] - -=head1 DESCRIPTION - -The B command takes a file containing a Netscape certificate -sequence and prints out the certificates contained in it or takes a -file of certificates and converts it into a Netscape certificate -sequence. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read or standard input if this -option is not specified. - -=item B<-out filename> - -specifies the output filename or standard output by default. - -=item B<-toseq> - -normally a Netscape certificate sequence will be input and the output -is the certificates contained in it. With the B<-toseq> option the -situation is reversed: a Netscape certificate sequence is created from -a file of certificates. - -=back - -=head1 EXAMPLES - -Output the certificates in a Netscape certificate sequence - - openssl nseq -in nseq.pem -out certs.pem - -Create a Netscape certificate sequence - - openssl nseq -in certs.pem -toseq -out nseq.pem - -=head1 NOTES - -The B encoded form uses the same headers and footers as a certificate: - - -----BEGIN CERTIFICATE----- - -----END CERTIFICATE----- - -A Netscape certificate sequence is a Netscape specific form that can be sent -to browsers as an alternative to the standard PKCS#7 format when several -certificates are sent to the browser: for example during certificate enrollment. -It is used by Netscape certificate server for example. - -=head1 BUGS - -This program needs a few more options: like allowing DER or PEM input and -output files and allowing multiple certificate files to be used. - -=cut diff --git a/doc/man/openssl.pod b/doc/man/openssl.pod deleted file mode 100644 index f5ce14ca2f..0000000000 --- a/doc/man/openssl.pod +++ /dev/null @@ -1,240 +0,0 @@ - -=pod - -=head1 NAME - -openssl - OpenSSL command line tool - -=head1 SYNOPSIS - -B -I -[ I ] -[ I ] - -=head1 DESCRIPTION - -OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL -v2/v3) and Transport Layer Security (TLS v1) network protocols and related -cryptography standards required by them. - -The B program is a command line tool for using the various -cryptography functions of OpenSSL's B library from the shell. -It can be used for - - o Creation of RSA, DH and DSA key parameters - o Creation 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 - -=head1 COMMAND SUMMARY - -The B program provides a rich variety of commands (I in the -SYNOPSIS above), each of which often has a wealth of options and arguments -(I and I in the SYNOPSIS). - -=head2 STANDARD COMMANDS - -=over 10 - -=item B - -Parse an ASN.1 sequence. - -=item B - -Certificate Authority (CA) Management. - -=item B - -Cipher Suite Description Determination. - -=item B - -Certificate Revocation List (CRL) Management. - -=item B - -CRL to PKCS#7 Conversion. - -=item B - -Message Digest Calculation. - -=item B - -Diffie-Hellman Data Management. - -=item B - -DSA Data Management. - -=item B - -DSA Parameter Generation. - -=item B - -Encoding with Ciphers. - -=item B - -Error Number to Error String Conversion. - -=item B - -Generation of Diffie-Hellman Parameters. - -=item B - -Generation of DSA Parameters. - -=item B - -Generation of RSA Parameters. - -=item B - -PKCS#7 Data Management. - -=item B - -X.509 Certificate Signing Request (CSR) Management. - -=item B - -RSA Data Management. - -=item B - -This implements a generic SSL/TLS client which can establish a transparent -connection to a remote server speaking SSL/TLS. It's intended for testing -purposes only and provides only rudimentary interface functionality but -internally uses mostly all functionality of the OpenSSL B library. - -=item B - -This implements a generic SSL/TLS server which accepts connections from remote -clients speaking SSL/TLS. It's intended for testing purposes only and provides -only rudimentary interface functionality but internally uses mostly all -functionality of the OpenSSL B library. It provides both an own command -line oriented protocol for testing SSL functions and a simple HTTP response -facility to emulate an SSL/TLS-aware webserver. - -=item B - -SSL Connection Timer. - -=item B - -SSL Session Data Management. - -=item B - -Algorithm Speed Measurement. - -=item B - -X.509 Certificate Verification. - -=item B - -OpenSSL Version Information. - -=item B - -X.509 Certificate Data Management. - -=back - -=head2 MESSAGE DIGEST COMMANDS - -=over 10 - -=item B - -MD2 Digest - -=item B - -MD5 Digest - -=item B - -MDC2 Digest - -=item B - -RMD-160 Digest - -=item B - -SHA Digest - -=item B - -SHA-1 Digest - -=back - -=head2 ENCODING AND CIPHER COMMANDS - -=over 10 - -=item B - -Base64 Encoding - -=item B - -Blowfish Cipher - -=item B - -CAST Cipher - -=item B - -CAST5 Cipher - -=item B - -DES Cipher - -=item B - -Triple-DES Cipher - -=item B - -IDEA Cipher - -=item B - -RC2 Cipher - -=item B - -RC4 Cipher - -=item B - -RC5 Cipher - -=back - -=head1 SEE ALSO - -asn1parse(1), ca(1), config(1), crl(1), crl2pkcs7(1), dgst(1), dh(1), -dsa(1), dsaparam(1), enc(1), gendh(1), gendsa(1), genrsa(1), nseq(1), -openssl(1), pkcs12(1), pkcs7(1), pkcs8(1), req(1), rsa(1), s_client(1), -s_server(1), smime(1), spkac(1), verify(1), version(1), x509(1), -crypto(3), ssl(3) - -=head1 HISTORY - -The openssl(1) document appeared in OpenSSL 0.9.2 - -=cut - diff --git a/doc/man/pkcs12.pod b/doc/man/pkcs12.pod deleted file mode 100644 index 14982096c1..0000000000 --- a/doc/man/pkcs12.pod +++ /dev/null @@ -1,286 +0,0 @@ - -=pod - -=head1 NAME - -pkcs12 - PKCS#12 file utility - -=head1 SYNOPSIS - -B B -[B<-export>] -[B<-chain>] -[B<-inkey filename>] -[B<-certfile filename>] -[B<-name name>] -[B<-caname name>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-nomacver>] -[B<-nocerts>] -[B<-clcerts>] -[B<-cacerts>] -[B<-nokeys>] -[B<-info>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-nodes>] -[B<-noiter>] -[B<-maciter>] -[B<-twopass>] -[B<-descert>] -[B<-certpbe>] -[B<-keypbe>] -[B<-keyex>] -[B<-keysig>] -[B<-password password>] -[B<-envpass var>] - -=head1 DESCRIPTION - -The B command allows PKCS#12 files (sometimes referred to as -PFX files) to be created and parsed. PKCS#12 files are used by several -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 -file can be created by using the B<-export> option (see below). - -=head1 PARSING OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies filename of the PKCS#12 file to be parsed. Standard input is used -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. - -=item B<-pass password> - -the PKCS#12 file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpass var> - -read the PKCS#12 file password from the environment variable B. - -=item B<-noout> - -this option inhibits output of the keys and certificates to the output file version -of the PKCS#12 file. - -=item B<-clcerts> - -only output client certificates (not CA certificates). - -=item B<-cacerts> - -only output CA certificates (not client certificates). - -=item B<-nocerts> - -no certificates at all will be output. - -=item B<-nokeys> - -no private keys will be output. - -=item B<-info> - -output additional information about the PKCS#12 file structure, algorithms used and -iteration counts. - -=item B<-des> - -use DES to encrypt private keys before outputting. - -=item B<-des3> - -use triple DES to encrypt private keys before outputting, this is the default. - -=item B<-idea> - -use IDEA to encrypt private keys before outputting. - -=item B<-nodes> - -don't encrypt the private keys at all. - -=item B<-nomacver> - -don't attempt to verify the integrity MAC before reading the file. - -=item B<-twopass> - -prompt for separate integrity and encryption passwords: most software -always assumes these are the same so this option will render such -PKCS#12 files unreadable. - -=back - -=head1 FILE CREATION OPTIONS - -=over 4 - -=item B<-export> - -This option specifies that a PKCS#12 file will be created rather than -parsed. - -=item B<-out filename> - -This specifies filename to write the PKCS#12 file to. Standard output is used -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. - -=item B<-inkey filename> - -file to read private key from. If not present then a private key must be present -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. - -=item B<-certfile filename> - -A filename to read additional certificates from. - -=item B<-caname friendlyname> - -This specifies the "friendly name" for other certificates. This option may be -used multiple times to specify names for all certificates in the order they -appear. Netscape ignores friendly names on other certificates whereas MSIE -displays them. - -=item B<-pass password> - -the PKCS#12 file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpass var> - -read the PKCS#12 file password from the environment variable B. - -=item B<-chain> - -if this option is present then an attempt is made to include the entire -certificate chain of the user certificate. The standard CA store is used -for this search. If the search fails it is considered a fatal error. - -=item B<-descert> - -encrypt the certificate using triple DES, this may render the PKCS#12 -file unreadable by some "export grade" software. By default the private -key is encrypted using triple DES and the certificate using 40 bit RC2. - -=item B<-keypbe alg>, B<-certpbe alg> - -these options allow the algorithm used to encrypt the private key and -certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms -can be selected it is advisable only to use PKCS#12 algorithms. See the list -in the B section for more information. - -=item B<-keyex|-keysig> - -specifies that the private key is to be used for key exchange or just signing. -This option is only interpreted by MSIE and similar MS software. Normally -"export grade" software will only allow 512 bit RSA keys to be used for -encryption purposes but arbitrary length keys for signing. The B<-keysig> -option marks the key for signing only. Signing only keys can be used for -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<-nomaciter>, B<-noiter> - -these options affect the iteration counts on the MAC and key algorithms. -Unless you wish to produce files compatible with MSIE 4.0 you should leave -these options alone. - -To discourage attacks by using large dictionaries of common passwords the -algorithm that derives keys from passwords can have an iteration count applied -to it: this causes a certain part of the algorithm to be repeated and slows it -down. The MAC is used to check the file integrity but since it will normally -have the same password as the keys and certificates it could also be attacked. -By default both MAC and encryption iteration counts are set to 2048, using -these options the MAC and encryption iteration counts can be set to 1, since -this reduces the file security you should not use these options unless you -really have to. Most software supports both MAC and key iteration counts. -MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> -option. - -=item B<-maciter> - -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. - -=back - -=head1 NOTES - -Although there are a large number of options most of them are very rarely -used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used -for PKCS#12 file creation B<-export> and B<-name> are also used. - -The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption -algorithms for private keys and certificates to be specified. Normally -the defaults are fine but occasionally software can't handle triple DES -encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can -be used to reduce the private key encryption to 40 bit RC2. A complete -description of all algorithms is contained in the B manual page. - -=head1 EXAMPLES - -Parse a PKCS#12 file and output it to a file: - - openssl pkcs12 -in file.p12 -out file.pem - -Output only client certificates to a file: - - openssl pkcs12 -in file.p12 -clcerts -out file.pem - -Don't encrypt the private key: - - openssl pkcs12 -in file.p12 -out file.pem -nodes - -Print some info about a PKCS#12 file: - - openssl pkcs12 -in file.p12 -info -noout - -Create a PKCS#12 file: - - openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" - -Include some extra certificates: - - openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ - -certfile othercerts.pem - -=head1 BUGS - -Some would argue that the PKCS#12 standard is one big bug :-) - -Need password options for the PEM files: this will probably be fixed before -release. - -=head1 SEE ALSO - -pkcs8(1) - diff --git a/doc/man/pkcs7.pod b/doc/man/pkcs7.pod deleted file mode 100644 index 0514c5d667..0000000000 --- a/doc/man/pkcs7.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -pkcs7 - PKCS#7 utility - -=head1 SYNOPSIS - -B B -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-print_certs>] -[B<-text>] -[B<-noout>] - -=head1 DESCRIPTION - -The B command processes PKCS#7 files in DER or PEM format. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. B format is DER encoded PKCS#7 -v1.5 structure.B (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=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 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<-print_certs> - -prints out any certificates or CRLs contained in the file. They are -preceded by their subject and issuer names in one line format. - -=item B<-text> - -prints out certificates details in full rather than just subject and -issuer names. - -=item B<-noout> - -don't output the encoded version of the PKCS#7 structure (or certificates -is B<-print_certs> is set). - -=back - -=head1 EXAMPLES - -Convert a PKCS#7 file from PEM to DER: - - openssl pkcs7 -in file.pem -outform DER -out file.der - -Output all certificates in a file: - - openssl pkcs7 -in file.pem -print_certs -out certs.pem - -=head1 RESTRICTIONS - -There is no option to print out all the fields of a PKCS#7 file. - -This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they -cannot currently parse, for example, the new CMS as described in RFC2630. - -=head1 SEE ALSO - -crl2pkcs7(1) - -=cut diff --git a/doc/man/pkcs8.pod b/doc/man/pkcs8.pod deleted file mode 100644 index 171b58b4b8..0000000000 --- a/doc/man/pkcs8.pod +++ /dev/null @@ -1,224 +0,0 @@ -=pod - -=head1 NAME - -pkcs8 - PKCS#8 format private key conversion tool - -=head1 SYNOPSIS - -B B -[B<-topk8>] -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin password>] -[B<-envpassin var>] -[B<-out filename>] -[B<-passout password>] -[B<-envpassout var>] -[B<-noiter>] -[B<-nocrypt>] -[B<-nooct>] -[B<-v2 alg>] -[B<-v1 alg>] - -=head1 DESCRIPTION - -The B command processes private keys in PKCS#8 format. It can handle -both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo -format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-topk8> - -Normally a PKCS#8 private key is expected on input and a traditional format -private key will be written. With the B<-topk8> option the situation is -reversed: it reads a traditional format private key and writes a PKCS#8 -format key. - -=item B<-inform DER|PEM> - -This specifies the input format. If a PKCS#8 format key is expected on input -then either a B or B encoded version of a PKCS#8 key will be -expected. Otherwise the B or B format of the traditional format -private key is used. - -=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 password> - -the input file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassin var> - -read the input file password from the environment variable B. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output by -default. If any encryption options are set then a pass phrase will be -prompted for. The output filename should B be the same as the input -filename. - -=item B<-passout password> - -the output file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassout var> - -read the output file password from the environment variable B. - -=item B<-nocrypt> - -PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo -structures using an appropriate password based encryption algorithm. With -this option an unencrypted PrivateKeyInfo structure is expected or output. -This option does not encrypt private keys at all and should only be used -when absolutely necessary. Certain software such as some versions of Java -code signing software used unencrypted private keys. - -=item B<-nooct> - -This option generates private keys in a broken format that some software -uses. Specifically the private key should be enclosed in a OCTET STRING -but some software just includes the structure itself without the -surrounding OCTET STRING. - -=item B<-v2 alg> - -This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8 -private keys are encrypted with the password based encryption algorithm -called B this uses 56 bit DES encryption but it -was the strongest encryption algorithm supported in PKCS#5 v1.5. Using -the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any -encryption algorithm such as 168 bit triple DES or 128 bit RC2 however -not many implementations support PKCS#5 v2.0 yet. If you are just using -private keys with OpenSSL then this doesn't matter. - -The B argument is the encryption algorithm to use, valid values include -B, B and B. It is recommended that B is used. - -=item B<-v1 alg> - -This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete -list of possible algorithms is included below. - -=back - -=head1 NOTES - -The encrypted form of a PEM encode PKCS#8 files uses the following -headers and footers: - - -----BEGIN ENCRYPTED PRIVATE KEY----- - -----END ENCRYPTED PRIVATE KEY----- - -The unencrypted form uses: - - -----BEGIN PRIVATE KEY----- - -----END PRIVATE KEY----- - -Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration -counts are more secure that those encrypted using the traditional -SSLeay compatible formats. So if additional security is considered -important the keys should be converted. - -The default encryption is only 56 bits because this is the encryption -that most current implementations of PKCS#8 will support. - -Some software may use PKCS#12 password based encryption algorithms -with PKCS#8 format private keys: these are handled automatically -but there is no option to produce them. - -It is possible to write out DER encoded encrypted private keys in -PKCS#8 format because the encryption details are included at an ASN1 -level whereas the traditional format includes them at a PEM level. - -=head1 PKCS#5 v1.5 and PKCS#12 algorithms. - -Various algorithms can be used with the B<-v1> command line option, -including PKCS#5 v1.5 and PKCS#12. These are described in more detail -below. - -=over 4 - -=item B - -These algorithms were included in the original PKCS#5 v1.5 specification. -They only offer 56 bits of protection since they both use DES. - -=item B - -These algorithms are not mentioned in the original PKCS#5 v1.5 specification -but they use the same key derivation algorithm and are supported by some -software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or -56 bit DES. - -=item B - -These algorithms use the PKCS#12 password based encryption algorithm and -allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. - -=back - -=head1 EXAMPLES - -Convert a private from traditional to PKCS#5 v2.0 format using triple -DES: - - openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem - -Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm -(DES): - - openssl pkcs8 -in key.pem -topk8 -out enckey.pem - -Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm -(3DES): - - openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES - -Read a DER unencrypted PKCS#8 format private key: - - openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem - -Convert a private key from any PKCS#8 format to traditional format: - - openssl pkcs8 -in pk8.pem -out key.pem - -=head1 STANDARDS - -Test vectors from this implementation were posted to the pkcs-tng mailing -list using triple DES, DES and RC2 with high iteration counts, several -people confirmed that they could decrypt the private keys produced and -Therefore it can be assumed that the PKCS#5 v2.0 implementation is -reasonably accurate at least as far as these algorithms are concerned. - -=head1 BUGS - -There should be an option that prints out the encryption algorithm -in use and other details such as the iteration count. - -PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private -key format for OpenSSL: for compatibility several of the utilities use -the old format at present. - -=head1 SEE ALSO - -dsa(1), rsa(1), genrsa(1), gendsa(1) - -=cut diff --git a/doc/man/req.pod b/doc/man/req.pod deleted file mode 100644 index e836f187ac..0000000000 --- a/doc/man/req.pod +++ /dev/null @@ -1,530 +0,0 @@ - -=pod - -=head1 NAME - -req - PKCS#10 certificate and certificate generating utility. - -=head1 SYNOPSIS - -B B -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin password>] -[B<-envpassin var>] -[B<-out filename>] -[B<-passout password>] -[B<-envpassout var>] -[B<-text>] -[B<-noout>] -[B<-verify>] -[B<-modulus>] -[B<-new>] -[B<-newkey rsa:bits>] -[B<-newkey dsa:file>] -[B<-nodes>] -[B<-key filename>] -[B<-keyform PEM|DER>] -[B<-keyout filename>] -[B<-[md5|sha1|md2|mdc2]>] -[B<-config filename>] -[B<-x509>] -[B<-days n>] -[B<-noasn1-kludge>] -[B<-extensions section>] -[B<-reqexts section>] - -=head1 DESCRIPTION - -The B command primarily creates and processes certificate requests -in PKCS#10 format. It can additionally create self signed certificates -for use as root CAs for example. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B option uses an ASN1 DER encoded -form compatible with the PKCS#10. The B form is the default format: it -consists of the B format base64 encoded with additional header and -footer lines. - -=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 request from or standard input -if this option is not specified. A request is only read if the creation -options (B<-new> and B<-newkey>) are not specified. - -=item B<-passin password> - -the input file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassin var> - -read the input file password from the environment variable B. - -=item B<-out filename> - -This specifies the output filename to write to or standard output by -default. - -=item B<-passout password> - -the output file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassout var> - -read the output file password from the environment variable B. - -=item B<-text> - -prints out the certificate request in text form. - -=item B<-noout> - -this option prevents output of the encoded version of the request. - -=item B<-modulus> - -this option prints out the value of the modulus of the public key -contained in the request. - -=item B<-verify> - -verifies the signature on the request. - -=item B<-new> - -this option generates a new certificate request. It will prompt -the user for the relevant field values. The actual fields -prompted for and their maximum and minimum sizes are specified -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<-newkey arg> - -this option creates a new certificate request and a new private -key. The argument takes one of two forms. B, where -B is the number of bits, generates an RSA key B -in size. B generates a DSA key using the parameters -in the file B. - -=item B<-key filename> - -This specifies the file to read the private key from. It also -accepts PKCS#8 format private keys for PEM format files. - -=item B<-keyform PEM|DER> - -the format of the private key file specified in the B<-key> -argument. PEM is the default. - -=item B<-keyout filename> - -this gives the filename to write the newly created private key to. -If this option is not specified then the filename present in the -configuration file is used. - -=item B<-nodes> - -if this option is specified then if a private key is created it -will not be encrypted. - -=item B<-[md5|sha1|md2|mdc2]> - -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. - -=item B<-config filename> - -this allows an alternative configuration file to be specified, -this overrides the compile time filename or any specified in -the B environment variable. - -=item B<-x509> - -this option outputs a self signed certificate instead of a certificate -request. This is typically used to generate a test certificate or -a self signed root CA. The extensions added to the certificate -(if any) are specified in the configuration file. - -=item B<-days n> - -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 -extensions (if the B<-x509> option is present) or certificate -request extensions. This allows several different sections to -be used in the same configuration file to specify requests for -a variety of purposes. - -=item B<-asn1-kludge> - -by default the B command outputs certificate requests containing -no attributes in the correct PKCS#10 format. However certain CAs will only -accept requests containing no attributes in an invalid form: this -option produces this invalid format. - -More precisely the B in a PKCS#10 certificate request -are defined as a B. They are B so -if no attributes are present then they should be encoded as an -empty B. The invalid form does not include the empty -B whereas the correct form does. - -It should be noted that very few CAs still require the use of this option. - -=back - -=head1 CONFIGURATION FILE FORMAT - -The configuration options are specified in the B section of -the configuration file. As with all configuration files if no -value is specified in the specific section (i.e. B) then -the initial unnamed or B section is searched too. - -The options available are described in detail below. - -=over 4 - -=item B - -The passwords for the input private key file (if present) and -the output private key file (if one will be created). The -command line options B, B, B and -B override the configuration file values. - -=item B - -This specifies the default key size in bits. If not specified then -512 is used. It is used if the B<-new> option is used. It can be -overridden by using the B<-newkey> option. - -=item B - -This is the default filename to write a private key to. If not -specified the key is written to standard output. This can be -overridden by the B<-keyout> option. - -=item B - -This specifies a file containing additional B. -Each line of the file should consist of the numerical form of the -object identifier followed by white space then the short name followed -by white space and finally the long name. - -=item B - -This specifies a section in the configuration file containing extra -object identifiers. Each line should consist of the short name of the -object identifier followed by B<=> and the numerical form. The short -and long names are the same when this option is used. - -=item B - -This specifies a filename in which random number seed information is -placed and read from. It is used for private key generation. - -=item B - -If this is set to B then if a private key is generated it is -B encrypted. This is equivalent to the B<-nodes> command line -option. For compatibility B is an equivalent option. - -=item B - -This option specifies the digest algorithm to use. Possible values -include B. If not present then MD5 is used. This -option can be overridden on the command line. - -=item B - -This option masks out the use of certain string types in certain -fields. Most users will not need to change this option. - -It can be set to several values B which is also the default -option uses PrintableStrings, T61Strings and BMPStrings if the -B value is used then only PrintableStrings and BMPStrings will -be used. This follows the PKIX recommendation in RFC2459. If the -B option is used then only UTF8Strings will be used: this -is the PKIX recommendation in RFC2459 after 2003. Finally the B -option just uses PrintableStrings and T61Strings: certain software has -problems with BMPStrings and UTF8Strings: in particular Netscape. - -=item B - -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. - -=item B - -this specifies the configuration file section containing a list of -extensions to add to certificate generated when the B<-x509> switch -is used. It can be overridden by the B<-extensions> command line switch. - -=item B - -if set to the value B this disables prompting of certificate fields -and just takes values from the config file directly. It also changes the -expected format of the B and B sections. - -=item B - -this specifies the section containing any request attributes: its format -is the same as B. Typically these may contain the -challengePassword or unstructuredName types. They are currently ignored -by OpenSSL's request signing utilities but some CAs might want them. - -=item B - -This specifies the section containing the distinguished name fields to -prompt for when generating a certificate or certificate request. The format -is described in the next section. - -=back - -=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT - -There are two separate formats for the distinguished name and attribute -sections. If the B option is set to B then these sections -just consist of field names and values: for example, - - CN=My Name - OU=My Organization - emailAddress=someone@somehere.org - -This allows external programs (e.g. GUI based) to generate a template file -with all the field names and values and just pass it to B. An example -of this kind of configuration files is contained in the B section. - -Alternatively if the B option is absent or not set to B the the -file contains field prompting information. It consists of lines of the form: - - fieldName="prompt" - fieldName_default="default field value" - fieldName_min= 2 - fieldName_max= 4 - -"fieldName" is the field name being used, for example commonName (or CN). -The "prompt" string is used to ask the user to enter the relevant -details. If the user enters nothing then the default value is used if no -default value is present then the field is omitted. A field can -still be omitted if a default value is present if the user just -enters the '.' character. - -The number of characters entered must be between the fieldName_min and -fieldName_max limits: there may be additional restrictions based -on the field being used (for example countryName can only ever be -two characters long and must fit in a PrintableString). - -Some fields (such as organizationName) can be used more than once -in a DN. This presents a problem because configuration files will -not recognize the same name occurring twice. To avoid this problem -if the fieldName contains an some characters followed by a full stop -they will be ignored. So for example a second organizationName can -be input by calling it "1.organizationName". - -The actual permitted field names are any object identifier short or -long names. These are compiled into OpenSSL and include the usual -values such as commonName, countryName, localityName, organizationName, -organizationUnitName, stateOrPrivinceName. Additionally emailAddress -is include as well as name, surname, givenName initials and dnQualifier -are supported. - -Additional object identifiers can be defined with the B or -B options in the configuration file. Any additional fields -will be treated as though they were a DirectoryString. - - -=head1 EXAMPLES - -Examine and verify certificate request: - - openssl req -in req.pem -text -verify -noout - -Create a private key and then generate a certificate request from it: - - openssl genrsa -out key.pem 1024 - openssl req -new -key key.pem -out req.pem - -The same but just using req: - - openssl req -newkey rsa:1024 -keyout key.pem -out req.pem - -Generate a self signed root certificate: - - openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem - -Example of a file pointed to by the B option: - - 1.2.3.4 shortName A longer Name - 1.2.3.6 otherName Other longer Name - -Example of a section pointed to by B making use of variable -expansion: - - testoid1=1.2.3.5 - testoid2=${testoid1}.6 - -Sample configuration file prompting for field values: - - [ req ] - default_bits = 1024 - default_keyfile = privkey.pem - distinguished_name = req_distinguished_name - attributes = req_attributes - x509_extensions = v3_ca - - dirstring_type = nobmp - - [ req_distinguished_name ] - countryName = Country Name (2 letter code) - countryName_default = AU - countryName_min = 2 - countryName_max = 2 - - localityName = Locality Name (eg, city) - - organizationalUnitName = Organizational Unit Name (eg, section) - - commonName = Common Name (eg, YOUR name) - commonName_max = 64 - - emailAddress = Email Address - emailAddress_max = 40 - - [ req_attributes ] - challengePassword = A challenge password - challengePassword_min = 4 - challengePassword_max = 20 - - [ v3_ca ] - - subjectKeyIdentifier=hash - authorityKeyIdentifier=keyid:always,issuer:always - basicConstraints = CA:true - -Sample configuration containing all field values: - - - RANDFILE = $ENV::HOME/.rnd - - [ req ] - default_bits = 1024 - default_keyfile = keyfile.pem - distinguished_name = req_distinguished_name - attributes = req_attributes - prompt = no - output_password = mypass - - [ req_distinguished_name ] - C = GB - ST = Test State or Province - L = Test Locality - O = Organization Name - OU = Organizational Unit Name - CN = Common Name - emailAddress = test@email.address - - [ req_attributes ] - challengePassword = A challenge password - - -=head1 NOTES - -The header and footer lines in the B format are respectively: - - -----BEGIN CERTIFICATE REQUEST---- - -----END CERTIFICATE REQUEST---- - -some software (some versions of Netscape certificate server) instead needs: - - -----BEGIN NEW CERTIFICATE REQUEST---- - -----END NEW CERTIFICATE REQUEST---- - -but is otherwise compatible. Either form is accepted on input. - -The certificate requests generated by B with MSIE have extensions -added. It includes the B extension which determines the type of -key (signature only or general purpose) and any additional OIDs entered -by the script in an extendedKeyUsage extension. - -=head1 DIAGNOSTICS - -The following messages are frequently asked about: - - Using configuration from /some/path/openssl.cnf - Unable to load config info - -This is followed some time later by... - - unable to find 'distinguished_name' in config - problems making Certificate Request - -The first error message is the clue: it can't find the configuration -file! Certain operations (like examining a certificate request) don't -need a configuration file so its use isn't enforced. Generation of -certificates or requests however does need a configuration file. This -could be regarded as a bug. - -Another puzzling message is this: - - Attributes: - a0:00 - -this is displayed when no attributes are present and the request includes -the correct empty B structure (the DER encoding of which is 0xa0 -0x00). If you just see: - - Attributes: - -then the B is missing and the encoding is technically invalid (but -it is tolerated). See the description of the command line option B<-asn1-kludge> -for more information. - -=head1 ENVIRONMENT VARIABLES - -The variable B if defined allows an alternative configuration -file location to be specified, it will be overridden by the B<-config> command -line switch if it is present. For compatibility reasons the B -environment variable serves the same purpose but its use is discouraged. - -=head1 BUGS - -OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively -treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. -This can cause problems if you need characters that aren't available in -PrintableStrings and you don't want to or can't use BMPStrings. - -As a consequence of the T61String handling the only correct way to represent -accented characters in OpenSSL is to use a BMPString: unfortunately Netscape -currently chokes on these. If you have to use accented characters with Netscape -and MSIE then you currently need to use the invalid T61String form. - -The current prompting is not very friendly. It doesn't allow you to confirm what -you've just entered. Other things like extensions in certificate requests are -statically defined in the configuration file. Some of these: like an email -address in subjectAltName should be input by the user. - -=head1 SEE ALSO - -x509(1), ca(1), genrsa(1), gendsa(1), config(5) - -=cut diff --git a/doc/man/rsa.pod b/doc/man/rsa.pod deleted file mode 100644 index 05c64eb470..0000000000 --- a/doc/man/rsa.pod +++ /dev/null @@ -1,160 +0,0 @@ - -=pod - -=head1 NAME - -rsa - RSA key processing tool - -=head1 SYNOPSIS - -B B -[B<-inform PEM|NET|DER>] -[B<-outform PEM|NET|DER>] -[B<-in filename>] -[B<-passin password>] -[B<-envpassin var>] -[B<-out filename>] -[B<-passout password>] -[B<-envpassout var>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-text>] -[B<-noout>] -[B<-modulus>] -[B<-check>] -[B<-pubin>] -[B<-pubout>] - -=head1 DESCRIPTION - -The B command processes RSA keys. They can be converted between various -forms and their components printed out. B this command uses the -traditional SSLeay compatible format for private key encryption: newer -applications should use the more secure PKCS#8 format using the B -utility. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|NET|PEM> - -This specifies the input format. The B option uses an ASN1 DER encoded -form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format. -The B form is the default format: it consists of the B format base64 -encoded with additional header and footer lines. On input PKCS#8 format private -keys are also accepted. The B 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. - -=item B<-outform DER|NET|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 password> - -the input file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassin var> - -read the input file password from the environment variable B. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output by -is not specified. If any encryption options are set then a pass phrase will be -prompted for. The output filename should B be the same as the input -filename. - -=item B<-passout password> - -the output file password. Since certain utilities like "ps" make the command line -visible this option should be used with caution. - -=item B<-envpassout var> - -read the output file password from the environment variable B. - -=item B<-des|-des3|-idea> - -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. A pass phrase is prompted for. -If none of these options is specified the key is written in plain text. This -means that using the B utility to read in an encrypted key with no -encryption option can be used to remove the pass phrase from a key, or by -setting the encryption options it can be use to add or change the pass phrase. -These options can only be used with PEM format output files. - -=item B<-text> - -prints out the various public or private key components in -plain text in addition to the encoded version. - -=item B<-noout> - -this option prevents output of the encoded version of the key. - -=item B<-modulus> - -this option prints out the value of the modulus of the key. - -=item B<-check> - -this option checks the consistency of an RSA private key. - -=item B<-pubin> - -by default a private key is input file with this option a public key is input -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. - -=back - -=head1 NOTES - -The PEM private key format uses the header and footer lines: - - -----BEGIN RSA PRIVATE KEY----- - -----END RSA PRIVATE KEY----- - -=head1 EXAMPLES - -To remove the pass phrase on an RSA private key: - -C - -To encrypt a private key using triple DES: - -C - -To convert a private key from PEM to DER format: - -C - -To print out the components of a private key to standard output: - -C - -To just output the public part of a private key: - -C - -=head1 SEE ALSO - -pkcs8(1), dsa(1), genrsa(1), gendsa(1) - -=cut diff --git a/doc/man/s_client.pod b/doc/man/s_client.pod deleted file mode 100644 index cd9093eaba..0000000000 --- a/doc/man/s_client.pod +++ /dev/null @@ -1,211 +0,0 @@ - -=pod - -=head1 NAME - -s_client - SSL/TLS client program - -=head1 SYNOPSIS - -B B -[B<-connect> host:port>] -[B<-verify depth>] -[B<-cert filename>] -[B<-key filename>] -[B<-CApath directory>] -[B<-CAfile filename>] -[B<-reconnect>] -[B<-pause>] -[B<-showcerts>] -[B<-debug>] -[B<-nbio_test>] -[B<-state>] -[B<-nbio>] -[B<-crlf>] -[B<-quiet>] -[B<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[B<-no_ssl2>] -[B<-no_ssl3>] -[B<-no_tls1>] -[B<-bugs>] -[B<-cipher cipherlist>] - -=head1 DESCRIPTION - -The B command implements a generic SSL/TLS client which connects -to a remote host using SSL/TLS. It is a I useful diagnostic tool for -SSL servers. - -=head1 OPTIONS - -=over 4 - -=item B<-connect host:port> - -This specifies the host and optional port to connect to. If not specified -then an attempt is made to connect to the local host on port 4433. - -=item B<-cert certname> - -The certificate to use, if one is requested by the server. The default is -not to use a certificate. - -=item B<-key keyfile> - -The private key to use. If not specified then the certificate file will -be used. - -=item B<-verify depth> - -The verify depth to use. This specifies the maximum length of the -server certificate chain and turns on server certificate verification. -Currently the verify operation continues after errors so all the problems -with a certificate chain can be seen. As a side effect the connection -will never fail due to a server certificate verify failure. - -=item B<-CApath directory> - -The directory to use for server certificate verification. This directory -must be in "hash format", see B for more information. These are -also used when building the client certificate chain. - -=item B<-CAfile file> - -A file containing trusted certificates to use during server authentication -and to use when attempting to build the client certificate chain. - -=item B<-reconnect> - -reconnects to the same server 5 times using the same session ID, this can -be used as a test that session caching is working. - -=item B<-pause> - -pauses 1 second between each read and write call. - -=item B<-showcerts> - -display the whole server certificate chain: normally only the server -certificate itself is displayed. - -=item B<-prexit> - -print session information when the program exits. This will always attempt -to print out information even if the connection fails. Normally information -will only be printed out once if the connection succeeds. This option is useful -because the cipher in use may be renegotiated or the connection may fail -because a client certificate is required or is requested only after an -attempt is made to access a certain URL. Note: the output produced by this -option is not always accurate because a connection might never have been -established. - -=item B<-state> - -prints out the SSL session states. - -=item B<-debug> - -print extensive debugging information including a hex dump of all traffic. - -=item B<-nbio_test> - -tests non blocking I/O - -=item B<-nbio> - -turns on non blocking I/O - -=item B<-crlf> - -this option translated a line feed from the terminal into CR+LF as required -by some servers. - -=item B<-quiet> - -inhibit printing of session and certificate information. - -=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 -the initial handshake uses a method which should be compatible with all -servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. - -Unfortunately there are a lot of ancient and broken servers in use which -cannot handle this technique and will fail to connect. Some servers only -work if TLS is turned off with the B<-no_tls> option others will only -support SSL v2 and may need the B<-ssl2> option. - -=item B<-bugs> - -there are several known bug in SSL and TLS implementations. Adding this -option enables various workarounds. - -=item B<-cipher cipherlist> - -this allows the cipher list sent by the client to be modified. See the -B command for more information. - -=back - -=head1 CONNECTED COMMANDS - -If a connection is established with an SSL server then any data received -from the server is displayed and any key presses will be sent to the -server. If the line begins with an B then the session will be -renegotiated. If the line begins with a B the connection will be closed -down. - -=head1 NOTES - -B can be used to debug SSL servers. To connect to an SSL HTTP -server the command: - - openssl s_client -connect servername:443 - -would typically be used (https uses port 443). If the connection succeeds -then an HTTP command can be given such as "GET /" to retrieve a web page. - -If the handshake fails then there are several possible causes, if it is -nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, -B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> can be tried -in case it is a buggy server. In particular you should play with these -options B submitting a bug report to an OpenSSL mailing list. - -A frequent problem when attempting to get client certificates working -is that a web client complains it has no certificates or gives an empty -list to choose from. This is normally because the server is not sending -the clients certificate authority in its "acceptable CA list" when it -requests a certificate. By using B the CA list can be viewed -and checked. However some servers only request client authentication -after a specific URL is requested. To obtain the list in this case it -is necessary to use the B<-prexit> command and send an HTTP request -for an appropriate page. - -If a certificate is specified on the command line using the B<-cert> -option it will not be used unless the server specifically requests -a client certificate. Therefor merely including a client certificate -on the command line is no guarantee that the certificate works. - -If there are problems verifying a server certificate then the -B<-showcerts> option can be used to show the whole chain. - -=head1 BUGS - -Because this program has a lot of options and also because some of -the techniques used are rather old, the C source of s_client is rather -hard to read and not a model of how things should be done. A typical -SSL client program would be much simpler. - -The B<-verify> option should really exit if the server verification -fails. - -The B<-prexit> option is a bit of a hack. We should really report -information whenever a session is renegotiated. - -=head1 SEE ALSO - -sess_id(1), s_server(1), ciphers(1) - -=cut diff --git a/doc/man/s_server.pod b/doc/man/s_server.pod deleted file mode 100644 index 5b6a20221d..0000000000 --- a/doc/man/s_server.pod +++ /dev/null @@ -1,262 +0,0 @@ - -=pod - -=head1 NAME - -s_server - SSL/TLS server program - -=head1 SYNOPSIS - -B B -[B<-accept port>] -[B<-context id>] -[B<-verify depth>] -[B<-Verify depth>] -[B<-cert filename>] -[B<-key keyfile>] -[B<-dcert filename>] -[B<-dkey keyfile>] -[B<-dhparam filename>] -[B<-nbio>] -[B<-nbio_test>] -[B<-crlf>] -[B<-debug>] -[B<-state>] -[B<-CApath directory>] -[B<-CAfile filename>] -[B<-nocert>] -[B<-cipher cipherlist>] -[B<-quiet>] -[B<-no_tmp_rsa>] -[B<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[B<-no_ssl2>] -[B<-no_ssl3>] -[B<-no_tls1>] -[B<-no_dhe>] -[B<-bugs>] -[B<-hack>] -[B<-www>] -[B<-WWW>] - -=head1 DESCRIPTION - -The B command implements a generic SSL/TLS server which listens -for connections on a given port using SSL/TLS. - -=head1 OPTIONS - -=over 4 - -=item B<-accept port> - -the TCP port to listen on for connections. If not specified 4433 is used. - -=item B<-context id> - -sets the SSL context id. If a client certificate is being requested then -this option must be set. It can be given any string value. - -=item B<-cert certname> - -The certificate to use, most servers cipher suites require the use of a -certificate and some require a certificate with a certain public key type: -for example the DSS cipher suites require a certificate containing a DSS -(DSA) key. If not specified then the filename "server.pem" will be used. - -=item B<-key keyfile> - -The private key to use. If not specified then the certificate file will -be used. - -=item B<-dcert filename>, B<-dkey keyname> - -specify an additional certificate and private key, these behave in the -same manner as the B<-cert> and B<-key> options except there is no default -if they are not specified (no additional certificate and key is used). As -noted above some cipher suites require a certificate containing a key of -a certain type. Some cipher suites need a certificate carrying an RSA key -and some a DSS (DSA) key. By using RSA and DSS certificates and keys -a server can support clients which only support RSA or DSS cipher suites -by using an appropriate certificate. - -=item B<-nocert> - -if this option is set then no certificate is used. This restricts the -cipher suites available to the anonymous ones (currently just anonymous -DH). - -=item B<-dhparam filename> - -the DH parameter file to use. The ephemeral DH cipher suites generate keys -using a set of DH parameters. If not specified then an attempt is made to -load the parameters from the server certificate file. If this fails then -a static set of parameters hard coded into the s_server program will be used. - -=item B<-nodhe> - -if this option is set then no DH parameters will be loaded effectively -disabling the ephemeral DH cipher suites. - -=item B<-no_tmp_rsa> - -certain export cipher suites sometimes use a temporary RSA key, this option -disables temporary RSA key generation. - -=item B<-verify depth>, B<-Verify depth> - -The verify depth to use. This specifies the maximum length of the -client certificate chain and makes the server request a certificate from -the client. With the B<-verify> option a certificate is requested but the -client does not have to send one, with the B<-Verify> option the client -must supply a certificate or an error occurs. - -=item B<-CApath directory> - -The directory to use for client certificate verification. This directory -must be in "hash format", see B for more information. These are -also used when building the server certificate chain. - -=item B<-CAfile file> - -A file containing trusted certificates to use during client authentication -and to use when attempting to build the server certificate chain. The list -is also used in the list of acceptable client CAs passed to the client when -a certificate is requested. - -=item B<-state> - -prints out the SSL session states. - -=item B<-debug> - -print extensive debugging information including a hex dump of all traffic. - -=item B<-nbio_test> - -tests non blocking I/O - -=item B<-nbio> - -turns on non blocking I/O - -=item B<-crlf> - -this option translated a line feed from the terminal into CR+LF. - -=item B<-quiet> - -inhibit printing of session and certificate information. - -=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 -the initial handshake uses a method which should be compatible with all -servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. - -=item B<-bugs> - -there are several known bug in SSL and TLS implementations. Adding this -option enables various workarounds. - -=item B<-hack> - -this option enables a further workaround for some some early Netscape -SSL code (?). - -=item B<-cipher cipherlist> - -this allows the cipher list sent by the client to be modified. See the -B command for more information. - -=item B<-www> - -sends a status message back to the client when it connects. This includes -lots of information about the ciphers used and various session parameters. -The output is in HTML format so this option will normally be used with a -web browser. - -=item B<-WWW> - -emulates a simple web server. Pages will be resolved relative to the -current directory, for example if the URL https://myhost/page.html is -requested the file ./page.html will be loaded. - -=back - -=head1 CONNECTED COMMANDS - -If a connection request is established with an SSL client and neither the -B<-www> nor the B<-WWW> option has been used then normally any data received -from the client is displayed and any key presses will be sent to the client. - -Certain single letter commands are also recognised which perform special -operations: these are listed below. - -=over 4 - -=item B - -end the current SSL connection but still accept new connections. - -=item B - -end the current SSL connection and exit. - -=item B - -renegotiate the SSL session. - -=item B - -renegotiate the SSL session and request a client certificate. - -=item B

- -send some plain text down the underlying TCP connection: this should -cause the client to disconnect due to a protocol violation. - -=item B - -print out some session cache status information. - -=back - -=head1 NOTES - -B can be used to debug SSL clients. To accept connections from -a web browser the command: - - openssl s_server -accept 443 -www - -can be used for example. - -Most web browsers (in particular Netscape and MSIE) only support RSA cipher -suites, so they cannot connect to servers which don't use a certificate -carrying an RSA key or a version of OpenSSL with RSA disabled. - -Although specifying an empty list of CAs when requesting a client certificate -is strictly speaking a protocol violation, some SSL clients interpret this to -mean any CA is acceptable. This is useful for debugging purposes. - -The session parameters can printed out using the B program. - -=head1 BUGS - -Because this program has a lot of options and also because some of -the techniques used are rather old, the C source of s_server is rather -hard to read and not a model of how things should be done. A typical -SSL server program would be much simpler. - -The output of common ciphers is wrong: it just gives the list of ciphers that -OpenSSL recognizes and the client supports. - -There should be a way for the B program to print out details of any -unknown cipher suites a client says it supports. - -=head1 SEE ALSO - -sess_id(1), s_client(1), ciphers(1) - -=cut diff --git a/doc/man/smime.pod b/doc/man/smime.pod deleted file mode 100644 index d0da967083..0000000000 --- a/doc/man/smime.pod +++ /dev/null @@ -1,313 +0,0 @@ -=pod - -=head1 NAME - -smime - S/MIME utility - -=head1 SYNOPSIS - -B B -[B<-encrypt>] -[B<-decrypt>] -[B<-sign>] -[B<-verify>] -[B<-pk7out>] -[B<-des>] -[B<-des3>] -[B<-rc2-40>] -[B<-rc2-64>] -[B<-rc2-128>] -[B<-in file>] -[B<-certfile file>] -[B<-signer file>] -[B<-recip file>] -[B<-in file>] -[B<-inkey file>] -[B<-out file>] -[B<-to addr>] -[B<-from ad>] -[B<-subject s>] -[B<-text>] -[cert.pem]... - -=head1 DESCRIPTION - -The B command handles S/MIME mail. It can encrypt, decrypt, sign and -verify S/MIME messages. - -=head1 COMMAND OPTIONS - -There are five 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. - -=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<-pk7out> - -takes an input message and writes out a PEM encoded PKCS#7 structure. - -=item B<-in filename> - -the input message to be encrypted or signed or the MIME message to -be decrypted or verified. - -=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<-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<-CAfile file> - -a file containing trusted CA certificates, only used with B<-verify>. - -=item B<-CApath dir> - -a directory containing trusted CA certificates, only used with -B<-verify>. This directory must be a standard certificate directory: that -is a hash of each subject name (using B) should be linked -to each certificate. - -=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128> - -the encryption algorithm to use. DES (56 bits), triple DES (168 bits) -or 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 is -used. Only used with B<-encrypt>. - -=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<-noverify> - -do not verify the signers certificate of a signed message. - -=item B<-nochain> - -do not do chain verification of signers certificates: that is don't -use the certificates in the signed message as untrusted CAs. - -=item B<-nosigs> - -don't try to verify the signatures on the 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<-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<-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. - -=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<-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. - -=item B - -one or more certificates of message recipients: used when encrypting -a message. - -=item B<-to, -from, -subject> - -the relevant mail headers. These are included outside the signed -portion of a message so they may be included manually. If signing -then many S/MIME mail clients check the signers certificate's email -address matches that specified in the From: address. - -=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 PKCS#7 enveloped data: PKCS#7 -encrypted data is used for other purposes. - -=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 PKCS#7 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 EXAMPLES - -Create a cleartext signed message: - - openssl smime -sign -in message.txt -text -out mail.msg - -signer mycert.pem - -Create and opaque signed message - - openssl smime -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 smime -sign -in in.txt -text -out mail.msg - -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem - -Send a signed message under Unix directly to sendmail, including headers: - - openssl smime -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 smime -verify -in mail.msg -signer user.pem -out signedtext.txt - -Send encrypted mail using triple DES: - - openssl smime -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 smime -sign -in ml.txt -signer my.pem -text | openssl -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 smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem - -=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. - -The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 -structures may cause parsing errors. - -=cut diff --git a/doc/man/spkac.pod b/doc/man/spkac.pod deleted file mode 100644 index 75d58e772b..0000000000 --- a/doc/man/spkac.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -spkac - SPKAC printing and generating utility - -=head1 SYNOPSIS - -B B -[B<-in filename>] -[B<-out filename>] -[B<-key keyfile>] -[B<-challenge string>] -[B<-spkac spkacname>] -[B<-spksect section>] -[B<-noout>] -[B<-verify>] - - -=head1 DESCRIPTION - -The B command processes Netscape signed public key and challenge -(SPKAC) files. It can print out their contents, verify the signature and -produce its own SPKACs from a supplied private key. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read from or standard input if this -option is not specified. Ignored if the B<-key> option is used. - -=item B<-out filename> - -specifies the output filename to write to or standard output by -default. - -=item B<-key keyfile> - -create an SPKAC file using the private key in B. The -B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if -present. - -=item B<-challenge string> - -specifies the challenge string if an SPKAC is being created. - -=item B<-spkac spkacname> - -allows an alternative name form the variable containing the -SPKAC. The default is "SPKAC". This option affects both -generated and input SPKAC files. - -=item B<-spksect section> - -allows an alternative name form the section containing the -SPKAC. The default is the default section. - -=item B<-noout> - -don't output the text version of the SPKAC (not used if an -SPKAC is being created). - -=item B<-verify> - -verifies the digital signature on the supplied SPKAC. - - -=back - -=head1 EXAMPLES - -Print out the contents of an SPKAC: - - openssl spkac -in spkac.cnf - -Verify the signature of an SPKAC: - - openssl spkac -in spkac.cnf -noout -verify - -Create an SPKAC using the challenge string "hello": - - openssl spkac -key key.pem -challenge hello -out spkac.cnf - -Example of an SPKAC, (long lines split up for clarity): - - SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\ - PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\ - PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\ - 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\ - 4= - -=head1 NOTES - -A created SPKAC with suitable DN components appended can be fed into -the B utility. - -SPKACs are typically generated by Netscape when a form is submitted -containing the B tag as part of the certificate enrollment -process. - -The challenge string permits a primitive form of proof of possession -of private key. By checking the SPKAC signature and a random challenge -string some guarantee is given that the user knows the private key -corresponding to the public key being certified. This is important in -some applications. Without this it is possible for a previous SPKAC -to be used in a "replay attack". - -=head1 SEE ALSO - -ca(1) - -=cut diff --git a/doc/man/verify.pod b/doc/man/verify.pod deleted file mode 100644 index 2ff261e29a..0000000000 --- a/doc/man/verify.pod +++ /dev/null @@ -1,273 +0,0 @@ -=pod - -=head1 NAME - -pkcs7 - PKCS#7 utility - -=head1 SYNOPSIS - -B B -[B<-CApath directory>] -[B<-CAfile file>] -[B<-purpose purpose>] -[B<-untrusted file>] -[B<-help>] -[B<-verbose>] -[B<->] -[certificates] - - -=head1 DESCRIPTION - -The B command verifies certificate chains. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-CApath directory> - -A directory of trusted certificates. The certificates should have names -of the form: hash.0 or have symbolic links to them of this -form ("hash" is the hashed certificate subject name: see the B<-hash> option -of the B utility). Under Unix the B script will automatically -create symbolic links to a directory of certificates. - -=item B<-CAfile file> - -A file of trusted certificates. The file should contain multiple certificates -in PEM format concatenated together. - -=item B<-untrusted file> - -A file of untrusted certificates. The file should contain multiple certificates - -=item B<-purpose purpose> - -the intended use for the certificate. Without this option no chain verification -will be done. Currently accepted uses are B, B, -B, B, B. See the B -section for more information. - -=item B<-help> - -prints out a usage message. - -=item B<-verbose> - -print extra information about the operations being performed. - -=item B<-> - -marks the last option. All arguments following this are assumed to be -certificate files. This is useful if the first certificate filename begins -with a B<->. - -=item B - -one or more certificates to verify. If no certificate filenames are included -then an attempt is made to read a certificate from standard input. They should -all be in PEM format. - - -=back - -=head1 VERIFY OPERATION - -The B program uses the same functions as the internal SSL and S/MIME -verification, therefore this description applies to these verify operations -too. - -There is one crucial difference between the verify operations performed -by the B program: wherever possible an attempt is made to continue -after an error whereas normally the verify operation would halt on the -first error. This allows all the problems with a certificate chain to be -determined. - -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. -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 -verify is a root certificate then an exact match must be found in the trusted -list. - -The second operation is to check every untrusted certificate's extensions for -consistency with the supplied purpose. If the B<-purpose> option is not included -then no checks are done. The supplied or "leaf" certificate must have extensions -compatible with the supplied purpose and all other certificates must also be valid -CA certificates. The precise extensions required are described in more detail in -the B section of the B utility. - -The third operation is to check the trust settings on the root CA. The root -CA should be trusted for the supplied purpose. For compatibility with previous -versions of SSLeay and OpenSSL a certificate with no trust settings is considered -to be valid for all purposes. - -The final operation is to check the validity of the certificate chain. The validity -period is checked against the current system time and the notBefore and notAfter -dates in the certificate. The certificate signatures are also checked at this -point. - -If all operations complete successfully then certificate is considered valid. If -any operation fails then the certificate is not valid. - -=head1 DIAGNOSTICS - -When a verify operation fails the output messages can be somewhat cryptic. The -general form of the error message is: - - server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) - error 24 at 1 depth lookup:invalid CA certificate - -The first line contains the name of the certificate being verified followed by -the subject name of the certificate. The second line contains the error number -and the depth. The depth is number of the certificate being verified when a -problem was detected starting with zero for the certificate being verified itself -then 1 for the CA that signed the certificate and so on. Finally a text version -of the error number is presented. - -An exhaustive list of the error codes and messages is shown below, this also -includes the name of the error code as defined in the header file x509_vfy.h -Some of the error codes are defined but never returned: these are described -as "unused". - -=over 4 - -=item B<0 X509_V_OK: ok> - -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. - -=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. - -=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> - -the certificate signature could not be decrypted. This means that the actual signature value -could not be determined rather than it not matching the expected value, this is only -meaningful for RSA keys. - -=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> - -the CRL signature could not be decrypted: this means that the actual signature value -could not be determined rather than it not matching the expected value. Unused. - -=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> - -the public key in the certificate SubjectPublicKeyInfo could not be read. - -=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> - -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. - -=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> - -the certificate is not yet valid: the notBefore date is after the current time. - -=item B<10 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> - -the CRL is not yet valid. Unused. - -=item B<11 X509_V_ERR_CERT_HAS_EXPIRED: Certificate has expired> - -the certificate has expired: that is the notAfter date is before the current time. - -=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> - -the CRL has expired. Unused. - -=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> - -the certificate notBefore field contains an invalid time. - -=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> - -the certificate notAfter field contains an invalid time. - -=item B<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. - -=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. - -=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> - -an error occurred trying to allocate memory. This should never happen. - -=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> - -the passed certificate is self signed and the same certificate cannot be found in the list of -trusted certificates. - -=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> - -the certificate chain could be built up using the untrusted certificates but the root could not -be found locally. - -=item B<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. - -=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> - -no signatures could be verified because the chain contains only one certificate and it is not -self signed. - -=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> - -the certificate chain length is greater than the supplied maximum depth. Unused. - -=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> - -the certificate has been revoked. Unused. - -=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> - -a CA certificate is invalid. Either it is not a CA or its extensions are not consistent -with the supplied purpose. - -=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> - -the basicConstraints pathlength parameter has been exceeded. - -=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> - -the supplied certificate cannot be used for the specified purpose. - -=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> - -the root CA is not marked as trusted for the specified purpose. - -=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> - -the root CA is marked to reject the specified purpose. - -=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> - -an application specific error. Unused. - -=back - -=head1 SEE ALSO - -x509(1) - -=cut diff --git a/doc/man/version.pod b/doc/man/version.pod deleted file mode 100644 index 69421d52cb..0000000000 --- a/doc/man/version.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -version - print version information - -=head1 SYNOPSIS - -B -[B<-a>] -[B<-v>] -[B<-b>] -[B<-o>] -[B<-f>] -[B<-p>] - -=head1 DESCRIPTION - -This command is used to print out version information about OpenSSL. - -=head1 OPTIONS - -=over 4 - -=item B<-a> - -all information, this is the same as setting all the other flags. - -=item B<-v> - -the current OpenSSL version. - -=item B<-b> - -the date the current version of OpenSSL was built. - -=item B<-o> - -option information: various options set when the library was built. - -=item B<-c> - -compilation flags. - -=item B<-p> - -platform setting. - -=back - -=head1 NOTES - -The output of B would typically be used when sending -in a bug report. - -=cut diff --git a/doc/man/x509.pod b/doc/man/x509.pod deleted file mode 100644 index 52ac949b18..0000000000 --- a/doc/man/x509.pod +++ /dev/null @@ -1,541 +0,0 @@ - -=pod - -=head1 NAME - -x509 - Certificate display and signing utility - -=head1 SYNOPSIS - -B B -[B<-inform DER|PEM|NET>] -[B<-outform DER|PEM|NET>] -[B<-keyform DER|PEM>] -[B<-CAform DER|PEM>] -[B<-CAkeyform DER|PEM>] -[B<-in filename>] -[B<-out filename>] -[B<-serial>] -[B<-hash>] -[B<-subject>] -[B<-issuer>] -[B<-startdate>] -[B<-enddate>] -[B<-purpose>] -[B<-dates>] -[B<-modulus>] -[B<-fingerprint>] -[B<-alias>] -[B<-noout>] -[B<-trustout>] -[B<-clrtrust>] -[B<-clrreject>] -[B<-addtrust arg>] -[B<-addreject arg>] -[B<-setalias arg>] -[B<-days arg>] -[B<-signkey filename>] -[B<-x509toreq>] -[B<-req>] -[B<-CA filename>] -[B<-CAkey filename>] -[B<-CAcreateserial>] -[B<-CAserial filename>] -[B<-text>] -[B<-C>] -[B<-md2|-md5|-sha1|-mdc2>] -[B<-clrext>] -[B<-extfile filename>] -[B<-extensions section>] - -=head1 DESCRIPTION - -The B command is a multi purpose certificate utility. It can be -used to display certificate information, convert certificates to -various forms, sign certificate requests like a "mini CA" or edit -certificate trust settings. - -Since there are a large number of options they will split up into -various sections. - - -=head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS - -=over 4 - -=item B<-inform DER|PEM|NET> - -This specifies the input format normally the command will expect an X509 -certificate but this can change if other options such as B<-req> are -present. The DER format is the DER encoding of the certificate and PEM -is the base64 encoding of the DER encoding with header and footer lines -added. The NET option is an obscure Netscape server format that is now -obsolete. - -=item B<-outform DER|PEM|NET> - -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 certificate from or standard input -if this option is not specified. - -=item B<-out filename> - -This specifies the output filename to write to or standard output by -default. - -=item B<-md2|-md5|-sha1|-mdc2> - -the digest to use. This affects any signing or display option that uses a message -digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not -specified then MD5 is used. If the key being used to sign with is a DSA key then -this option has no effect: SHA1 is always used with DSA keys. - - -=back - -=head1 DISPLAY OPTIONS - -Note: the B<-alias> and B<-purpose> options are also display options -but are described in the B section. - -=over 4 - -=item B<-text> - -prints out the certificate in text form. Full details are output including the -public key, signature algorithms, issuer and subject names, serial number -any extensions present and any trust settings. - -=item B<-noout> - -this option prevents output of the encoded version of the request. - -=item B<-modulus> - -this option prints out the value of the modulus of the public key -contained in the certificate. - -=item B<-serial> - -outputs the certificate serial number. - -=item B<-hash> - -outputs the "hash" of the certificate subject name. This is used in OpenSSL to -form an index to allow certificates in a directory to be looked up by subject -name. - -=item B<-subject> - -outputs the subject name. - -=item B<-issuer> - -outputs the issuer name. - -=item B<-startdate> - -prints out the start date of the certificate, that is the notBefore date. - -=item B<-enddate> - -prints out the expiry date of the certificate, that is the notAfter date. - -=item B<-dates> - -prints out the start and expiry dates of a certificate. - -=item B<-fingerprint> - -prints out the digest of the DER encoded version of the whole certificate. - -=item B<-C> - -this outputs the certificate in the form of a C source file. - -=back - -=head1 TRUST SETTINGS - -Please note these options are currently experimental and may well change. - -A B is an ordinary certificate which has several -additional pieces of information attached to it such as the permitted -and prohibited uses of the certificate and an "alias". - -Normally when a certificate is being verified at least one certificate -must be "trusted". By default a trusted certificate must be stored -locally and must be a root CA: any certificate chain ending in this CA -is then usable for any purpose. - -Trust settings currently are only used with a root CA. They allow a finer -control over the purposes the root CA can be used for. For example a CA -may be trusted for SSL client but not SSL server use. - -See the description of the B utility for more information on the -meaning of trust settings. - -Future versions of OpenSSL will recognise trust settings on any -certificate: not just root CAs. - - -=over 4 - -=item B<-trustout> - -this causes B to output a B certificate. An ordinary -or trusted certificate can be input but by default an ordinary -certificate is output and any trust settings are discarded. With the -B<-trustout> option a trusted certificate is output. A trusted -certificate is automatically output if any trust settings are modified. - -=item B<-setalias arg> - -sets the alias of the certificate. This will allow the certificate -to be referred to using a nickname for example "Steve's Certificate". - -=item B<-alias> - -outputs the certificate alias, if any. - -=item B<-clrtrust> - -clears all the permitted or trusted uses of the certificate. - -=item B<-clrreject> - -clears all the prohibited or rejected uses of the certificate. - -=item B<-addtrust arg> - -adds a trusted certificate use. Currently acceptable values -are B (any purpose), B (SSL client use), B -(SSL server use) B (S/MIME email) and B (Object signing). - -=item B<-addreject arg> - -adds a prohibited use. It accepts the same values as the B<-addtrust> -option. - -=item B<-purpose> - -this option performs tests on the certificate extensions and outputs -the results. For a more complete description see the B section. - -=back - -=head1 SIGNING OPTIONS - -The B utility can be used to sign certificates and requests: it -can thus behave like a "mini CA". - -=over 4 - -=item B<-signkey filename> - -this option causes the input file to be self signed using the supplied -private key. - -If the input file is a certificate it sets the issuer name to the -subject name (i.e. makes it self signed) changes the public key to the -supplied value and changes the start and end dates. The start date is -set to the current time and the end date is set to a value determined -by the B<-days> option. Any certificate extensions are retained unless -the B<-clrext> option is supplied. - -If the input is a certificate request then a self signed certificate -is created using the supplied private key using the subject name in -the request. - -=item B<-clrext> - -delete any extensions from a certificate. This option is used when a -certificate is being created from another certificate (for example with -the B<-signkey> or the B<-CA> options). Normally all extensions are -retained. - -=item B<-keyform PEM|DER> - -specifies the format (DER or PEM) of the private key file used in the -B<-signkey> option. - -=item B<-days arg> - -specifies the number of days to make a certificate valid for. The default -is 30 days. - -=item B<-x509toreq> - -converts a certificate into a certificate request. The B<-signkey> option -is used to pass the required private key. - -=item B<-req> - -by default a certificate is expected on input. With this option a -certificate request is expected instead. - -=item B<-CA filename> - -specifies the CA certificate to be used for signing. When this option is -present B behaves like a "mini CA". The input file is signed by this -CA using this option: that is its issuer name is set to the subject name -of the CA and it is digitally signed using the CAs private key. - -This option is normally combined with the B<-req> option. Without the -B<-req> option the input is a certificate which must be self signed. - -=item B<-CAkey filename> - -sets the CA private key to sign a certificate with. If this option is -not specified then it is assumed that the CA private key is present in -the CA certificate file. - -=item B<-CAserial filename> - -sets the CA serial number file to use. - -When the B<-CA> option is used to sign a certificate it uses a serial -number specified in a file. This file consist of one line containing -an even number of hex digits with the serial number to use. After each -use the serial number is incremented and written out to the file again. - -The default filename consists of the CA certificate file base name with -".srl" appended. For example if the CA certificate file is called -"mycacert.pem" it expects to find a serial number file called "mycacert.srl". - -=item B<-CAcreateserial filename> - -with this option the CA serial number file is created if it does not exist: -it will contain the serial number "01". Normally if the B<-CA> option is -specified and the serial number file does not exist it is an error. - -=item B<-extfile filename> - -file containing certificate extensions to use. If not specified then -no extensions are added to the certificate. - -=item B<-extensions section> - -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. - -=back - -=head1 EXAMPLES - -Note: in these examples the '\' means the example should be all on one -line. - -Display the contents of a certificate: - - openssl x509 -in cert.pem -noout -text - -Display the certificate serial number: - - openssl x509 -in cert.pem -noout -serial - -Display the certificate MD5 fingerprint: - - openssl x509 -in cert.pem -noout -fingerprint - -Display the certificate SHA1 fingerprint: - - openssl x509 -sha1 -in cert.pem -noout -fingerprint - -Convert a certificate from PEM to DER format: - - openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER - -Convert a certificate to a certificate request: - - openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem - -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 \ - -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 \ - -CA cacert.pem -CAkey key.pem -CAcreateserial - - -Set a certificate to be trusted for SSL client use and change set its alias to -"Steve's Class 1 CA" - - openssl x509 -in cert.pem -addtrust sslclient \ - -alias "Steve's Class 1 CA" -out trust.pem - -=head1 NOTES - -The PEM format uses the header and footer lines: - - -----BEGIN CERTIFICATE---- - -----END CERTIFICATE---- - -it will also handle files containing: - - -----BEGIN X509 CERTIFICATE---- - -----END X509 CERTIFICATE---- - -Trusted certificates have the lines - - -----BEGIN TRUSTED CERTIFICATE---- - -----END TRUSTED CERTIFICATE---- - -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 -two certificates with the same fingerprint can be considered to be the same. - -The Netscape fingerprint uses MD5 whereas MSIE uses SHA1. - -=head1 CERTIFICATE EXTENSIONS - -The B<-purpose> option checks the certificate extensions and determines -what the certificate can be used for. The actual checks done are rather -complex and include various hacks and workarounds to handle broken -certificates and software. - -The same code is used when verifying untrusted certificates in chains -so this section is useful if a chain is rejected by the verify code. - -The basicConstraints extension CA flag is used to determine whether the -certificate can be used as a CA. If the CA flag is true then it is a CA, -if the CA flag is false then it is not a CA. B CAs should have the -CA flag set to true. - -If the basicConstraints extension is absent then the certificate is -considered to be a "possible CA" other extensions are checked according -to the intended use of the certificate. A warning is given in this case -because the certificate should really not be regarded as a CA: however -it is allowed to be a CA to work around some broken software. - -If the certificate is a V1 certificate (and thus has no extensions) and -it is self signed it is also assumed to be a CA but a warning is again -given: this is to work around the problem of Verisign roots which are V1 -self signed certificates. - -If the keyUsage extension is present then additional restraints are -made on the uses of the certificate. A CA certificate B have the -keyCertSign bit set if the keyUsage extension is present. - -The extended key usage extension places additional restrictions on the -certificate uses. If this extension is present (whether critical or not) -the key can only be used for the purposes specified. - -A complete description of each test is given below. The comments about -basicConstraints and keyUsage and V1 certificates above apply to B -CA certificates. - - -=over 4 - -=item B - -The extended key usage extension must be absent or include the "web client -authentication" OID. keyUsage must be absent or it must have the -digitalSignature bit set. Netscape certificate type must be absent or it must -have the SSL client bit set. - -=item B - -The extended key usage extension must be absent or include the "web client -authentication" OID. Netscape certificate type must be absent or it must have -the SSL CA bit set: this is used as a work around if the basicConstraints -extension is absent. - -=item B - -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. keyUsage must be absent or it -must have the digitalSignature, the keyEncipherment set or both bits set. -Netscape certificate type must be absent or have the SSL server bit set. - -=item B - -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. Netscape certificate type must -be absent or the SSL CA bit must be set: this is used as a work around if the -basicConstraints extension is absent. - -=item B - -For Netscape SSL clients to connect to an SSL server it must have the -keyEncipherment bit set if the keyUsage extension is present. This isn't -always valid because some cipher suites use the key for digital signing. -Otherwise it is the same as a normal SSL server. - -=item B - -The extended key usage extension must be absent or include the "email -protection" OID. Netscape certificate type must be absent or should have the -S/MIME bit set. If the S/MIME bit is not set in netscape certificate type -then the SSL client bit is tolerated as an alternative but a warning is shown: -this is because some Verisign certificates don't set the S/MIME bit. - -=item B - -In addition to the common S/MIME client tests the digitalSignature bit must -be set if the keyUsage extension is present. - -=item B - -In addition to the common S/MIME tests the keyEncipherment bit must be set -if the keyUsage extension is present. - -=item B - -The extended key usage extension must be absent or include the "email -protection" OID. Netscape certificate type must be absent or must have the -S/MIME CA bit set: this is used as a work around if the basicConstraints -extension is absent. - -=item B - -The keyUsage extension must be absent or it must have the CRL signing bit -set. - -=item B - -The normal CA tests apply. Except in this case the basicConstraints extension -must be present. - -=back - -=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. - -It is possible to produce invalid certificates or requests by specifying the -wrong private key or using inconsistent options in some cases: these should -be checked. - -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 -is currently being developed. It thus describes the intended behavior rather -than the current behaviour. It is hoped that it will represent reality in -OpenSSL 0.9.5 and later. - -=head1 SEE ALSO - -req(1), ca(1), genrsa(1), gendsa(1), verify(1) - -=cut