Document the nameopt change
[openssl.git] / doc / apps / x509.pod
index ca691bb4f24755963e2ea3b293dddffd5e3d4163..a0127fe0f6b3737ca7194bb9625fe3370a417435 100644 (file)
@@ -19,15 +19,19 @@ B<openssl> B<x509>
 [B<-hash>]
 [B<-subject_hash>]
 [B<-issuer_hash>]
+[B<-ocspid>]
 [B<-subject>]
 [B<-issuer>]
 [B<-nameopt option>]
 [B<-email>]
+[B<-ocsp_uri>]
 [B<-startdate>]
 [B<-enddate>]
 [B<-purpose>]
 [B<-dates>]
+[B<-checkend num>]
 [B<-modulus>]
+[B<-pubkey>]
 [B<-fingerprint>]
 [B<-alias>]
 [B<-noout>]
@@ -40,13 +44,16 @@ B<openssl> B<x509>
 [B<-days arg>]
 [B<-set_serial n>]
 [B<-signkey filename>]
+[B<-passin arg>]
 [B<-x509toreq>]
 [B<-req>]
 [B<-CA filename>]
 [B<-CAkey filename>]
 [B<-CAcreateserial>]
 [B<-CAserial filename>]
+[B<-force_pubkey key>]
 [B<-text>]
+[B<-certopt option>]
 [B<-C>]
 [B<-md2|-md5|-sha1|-mdc2>]
 [B<-clrext>]
@@ -103,7 +110,7 @@ then this option has no effect: SHA1 is always used with DSA keys.
 
 =item B<-engine id>
 
-specifying an engine (by it's unique B<id> string) will cause B<req>
+specifying an engine (by its unique B<id> string) will cause B<x509>
 to attempt to obtain a functional reference to the specified engine,
 thus initialising it if needed. The engine will then be set as the default
 for all available algorithms.
@@ -134,6 +141,10 @@ section for more information.
 
 this option prevents output of the encoded version of the request.
 
+=item B<-pubkey>
+
+outputs the the certificate's SubjectPublicKeyInfo block in PEM format.
+
 =item B<-modulus>
 
 this option prints out the value of the modulus of the public key
@@ -153,9 +164,23 @@ name.
 
 outputs the "hash" of the certificate issuer name.
 
+=item B<-ocspid>
+
+outputs the OCSP hash values for the subject name and public key.
+
 =item B<-hash>
 
-synonym for "-hash" for backward compatibility reasons.
+synonym for "-subject_hash" for backward compatibility reasons.
+
+=item B<-subject_hash_old>
+
+outputs the "hash" of the certificate subject name using the older algorithm
+as used by OpenSSL versions before 1.0.0.
+
+=item B<-issuer_hash_old>
+
+outputs the "hash" of the certificate issuer name using the older algorithm
+as used by OpenSSL versions before 1.0.0.
 
 =item B<-subject>
 
@@ -176,6 +201,10 @@ set multiple options. See the B<NAME OPTIONS> section for more information.
 
 outputs the email address(es) if any.
 
+=item B<-ocsp_uri>
+
+outputs the OCSP responder address(es) if any.
+
 =item B<-startdate>
 
 prints out the start date of the certificate, that is the notBefore date.
@@ -188,6 +217,11 @@ prints out the expiry date of the certificate, that is the notAfter date.
 
 prints out the start and expiry dates of a certificate.
 
+=item B<-checkend arg>
+
+checks if the certificate expires within the next B<arg> seconds and exits
+non-zero if yes it will expire or zero if not.
+
 =item B<-fingerprint>
 
 prints out the digest of the DER encoded version of the whole certificate
@@ -293,6 +327,11 @@ 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<-passin arg>
+
+the key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
 =item B<-clrext>
 
 delete any extensions from a certificate. This option is used when a
@@ -327,8 +366,7 @@ the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
 option the serial number file (as specified by the B<-CAserial> or
 B<-CAcreateserial> options) is not used.
 
-The serial number can be decimal or hex (if preceded by B<0x>). Negative
-serial numbers can also be specified but their use is not recommended.
+The serial number can be decimal or hex (if preceded by B<0x>).
 
 =item B<-CA filename>
 
@@ -363,8 +401,9 @@ The default filename consists of the CA certificate file base name with
 
 with this option the CA serial number file is created if it does not exist:
 it will contain the serial number "02" and the certificate being signed will
-have the 1 as its serial number. Normally if the B<-CA> option is specified
-and the serial number file does not exist it is an error.
+have the 1 as its serial number. If the B<-CA> option is specified
+and the serial number file does not exist a random number is generated;
+this is the recommended practice.
 
 =item B<-extfile filename>
 
@@ -380,6 +419,15 @@ specified then the extensions should either be contained in the unnamed
 L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
 extension section format.
 
+=item B<-force_pubkey key>
+
+when a certificate is created set its public key to B<key> instead of the
+key in the certificate or certificate request. This option is useful for
+creating certificates where the algorithm can't normally sign requests, for
+example DH.
+
+The format or B<key> can be specified using the B<-keyform> option.
+
 =back
 
 =head2 NAME OPTIONS
@@ -394,7 +442,7 @@ a B<-> to turn the option off. Only the first four will normally be used.
 
 =item B<compat>
 
-use the old format. This is equivalent to specifying no name options at all.
+use the old format.
 
 =item B<RFC2253>
 
@@ -406,13 +454,13 @@ B<sep_comma_plus>, B<dn_rev> and B<sname>.
 
 a oneline format which is more readable than RFC2253. It is equivalent to
 specifying the  B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
-B<dump_der>, B<use_quote>, B<sep_comma_plus_spc>, B<spc_eq> and B<sname>
-options.
+B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
+options.  This is the I<default> of no name options are given explicitely.
 
 =item B<multiline>
 
 a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
-B<spc_eq>, B<lname> and B<align>.
+B<space_eq>, B<lname> and B<align>.
 
 =item B<esc_2253>
 
@@ -448,7 +496,7 @@ using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
 Also if this option is off any UTF8Strings will be converted to their
 character form first.
 
-=item B<no_type>
+=item B<ignore_type>
 
 this option does not attempt to interpret multibyte characters in any
 way. That is their content octets are merely dumped as though one octet
@@ -512,7 +560,7 @@ diagnostic purpose.
 align field values for a more readable output. Only usable with
 B<sep_multiline>.
 
-=item B<spc_eq>
+=item B<space_eq>
 
 places spaces round the B<=> character which follows the field
 name.
@@ -622,7 +670,7 @@ Display the certificate subject name in RFC2253 form:
 Display the certificate subject name in oneline form on a terminal
 supporting UTF8:
 
- openssl x509 -in cert.pem -noout -subject -nameopt oneline,-escmsb
+ openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
 
 Display the certificate MD5 fingerprint:
 
@@ -832,4 +880,10 @@ L<x509v3_config(5)|x509v3_config(5)>
 
 Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
 
+The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
+before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
+of the distinguished name. In OpenSSL 1.0.0 and later it is based on a
+canonical version of the DN using SHA1. This means that any directories using
+the old form must have their links rebuilt using B<c_rehash> or similar. 
+
 =cut