[thirdparty/openssl.git] / doc / apps / spkac.pod

=pod

=head1 NAME

spkac - SPKAC printing and generating utility

=head1 SYNOPSIS

B<openssl> B<spkac>
[B<-in filename>]
[B<-out filename>]
[B<-key keyfile>]
[B<-passin arg>]
[B<-challenge string>]
[B<-pubkey>]
[B<-spkac spkacname>]
[B<-spksect section>]
[B<-noout>]
[B<-verify>]
[B<-engine id>]

=head1 DESCRIPTION

The B<spkac> 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<keyfile>. The
B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
present.

=item B<-passin password>

the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.

=item B<-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<-pubkey>

output the public key of an SPKAC (not used if an SPKAC is
being created).

=item B<-verify>

verifies the digital signature on the supplied SPKAC.

=item B<-engine id>

specifying an engine (by its unique B<id> string) will cause B<spkac>
to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.

=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<ca> utility.

SPKACs are typically generated by Netscape when a form is submitted
containing the B<KEYGEN> 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

L<ca(1)|ca(1)>

=cut
Commit	Line	Data
01aad2c8 DSH	1	=pod
	2
	3	=head1 NAME
	4
	5	spkac - SPKAC printing and generating utility
	6
	7	=head1 SYNOPSIS
	8
	9	B<openssl> B<spkac>
	10	[B<-in filename>]
	11	[B<-out filename>]
	12	[B<-key keyfile>]
a3fe382e	13	[B<-passin arg>]
01aad2c8	14	[B<-challenge string>]
82fc1d9c	15	[B<-pubkey>]
01aad2c8 DSH	16	[B<-spkac spkacname>]
	17	[B<-spksect section>]
	18	[B<-noout>]
	19	[B<-verify>]
bfa35550	20	[B<-engine id>]
01aad2c8 DSH	21
	22	=head1 DESCRIPTION
	23
	24	The B<spkac> command processes Netscape signed public key and challenge
	25	(SPKAC) files. It can print out their contents, verify the signature and
	26	produce its own SPKACs from a supplied private key.
	27
	28	=head1 COMMAND OPTIONS
	29
	30	=over 4
	31
	32	=item B<-in filename>
	33
	34	This specifies the input filename to read from or standard input if this
	35	option is not specified. Ignored if the B<-key> option is used.
	36
	37	=item B<-out filename>
	38
	39	specifies the output filename to write to or standard output by
	40	default.
	41
	42	=item B<-key keyfile>
	43
	44	create an SPKAC file using the private key in B<keyfile>. The
	45	B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
	46	present.
	47
f07fb9b2 DSH	48	=item B<-passin password>
f07fb9b2 DSH	49
a3fe382e DSH	50	the input file password source. For more information about the format of B<arg>
a3fe382e DSH	51	see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)\|openssl(1)>.
f07fb9b2	52
01aad2c8 DSH	53	=item B<-challenge string>
	54
	55	specifies the challenge string if an SPKAC is being created.
	56
	57	=item B<-spkac spkacname>
	58
	59	allows an alternative name form the variable containing the
	60	SPKAC. The default is "SPKAC". This option affects both
	61	generated and input SPKAC files.
	62
	63	=item B<-spksect section>
	64
	65	allows an alternative name form the section containing the
	66	SPKAC. The default is the default section.
	67
	68	=item B<-noout>
	69
	70	don't output the text version of the SPKAC (not used if an
	71	SPKAC is being created).
	72
82fc1d9c DSH	73	=item B<-pubkey>
	74
	75	output the public key of an SPKAC (not used if an SPKAC is
	76	being created).
	77
01aad2c8 DSH	78	=item B<-verify>
	79
	80	verifies the digital signature on the supplied SPKAC.
	81
bfa35550 RL	82	=item B<-engine id>
bfa35550 RL	83
e5fa864f	84	specifying an engine (by its unique B<id> string) will cause B<spkac>
bfa35550 RL	85	to attempt to obtain a functional reference to the specified engine,
	86	thus initialising it if needed. The engine will then be set as the default
	87	for all available algorithms.
01aad2c8 DSH	88
	89	=back
	90
	91	=head1 EXAMPLES
	92
	93	Print out the contents of an SPKAC:
	94
19d2bb57	95	openssl spkac -in spkac.cnf
01aad2c8 DSH	96
	97	Verify the signature of an SPKAC:
	98
19d2bb57	99	openssl spkac -in spkac.cnf -noout -verify
01aad2c8 DSH	100
	101	Create an SPKAC using the challenge string "hello":
	102
	103	openssl spkac -key key.pem -challenge hello -out spkac.cnf
	104
	105	Example of an SPKAC, (long lines split up for clarity):
	106
	107	SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\
	108	PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\
	109	PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\
	110	2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\
	111	4=
	112
	113	=head1 NOTES
	114
	115	A created SPKAC with suitable DN components appended can be fed into
	116	the B<ca> utility.
	117
	118	SPKACs are typically generated by Netscape when a form is submitted
	119	containing the B<KEYGEN> tag as part of the certificate enrollment
	120	process.
	121
	122	The challenge string permits a primitive form of proof of possession
	123	of private key. By checking the SPKAC signature and a random challenge
	124	string some guarantee is given that the user knows the private key
	125	corresponding to the public key being certified. This is important in
	126	some applications. Without this it is possible for a previous SPKAC
	127	to be used in a "replay attack".
	128
	129	=head1 SEE ALSO
	130
bb075f88	131	L<ca(1)\|ca(1)>
01aad2c8 DSH	132
01aad2c8 DSH	133	=cut