[thirdparty/openssl.git] / doc / man3 / SCT_validate.pod

=pod

=head1 NAME

SCT_validate, SCT_LIST_validate, SCT_get_validation_status -
checks Signed Certificate Timestamps (SCTs) are valid

=head1 SYNOPSIS

 #include <openssl/ct.h>

 typedef enum {
     SCT_VALIDATION_STATUS_NOT_SET,
     SCT_VALIDATION_STATUS_UNKNOWN_LOG,
     SCT_VALIDATION_STATUS_VALID,
     SCT_VALIDATION_STATUS_INVALID,
     SCT_VALIDATION_STATUS_UNVERIFIED,
     SCT_VALIDATION_STATUS_UNKNOWN_VERSION
 } sct_validation_status_t;

 int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx);
 int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx);
 sct_validation_status_t SCT_get_validation_status(const SCT *sct);

=head1 DESCRIPTION

SCT_validate() will check that an SCT is valid and verify its signature.
SCT_LIST_validate() performs the same checks on an entire stack of SCTs.
The result of the validation checks can be obtained by passing the SCT to
SCT_get_validation_status().

A CT_POLICY_EVAL_CTX must be provided that specifies:

=over 2

=item *

The certificate the SCT was issued for.

Failure to provide the certificate will result in the validation status being
SCT_VALIDATION_STATUS_UNVERIFIED.

=item *

The issuer of that certificate.

This is only required if the SCT was issued for a pre-certificate
(see RFC 6962). If it is required but not provided, the validation status will
be SCT_VALIDATION_STATUS_UNVERIFIED.

=item *

A CTLOG_STORE that contains the CT log that issued this SCT.

If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.

=back

If the SCT is of an unsupported version (only v1 is currently supported), the
validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION.

If the SCT's signature is incorrect, its timestamp is in the future (relative to
the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation
status will be SCT_VALIDATION_STATUS_INVALID.

If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID.

=head1 NOTES

A return value of 0 from SCT_LIST_validate() should not be interpreted as a
failure. At a minimum, only one valid SCT may provide sufficient confidence
that a certificate has been publicly logged.

=head1 RETURN VALUES

SCT_validate() returns a negative integer if an internal error occurs, 0 if the
SCT fails validation, or 1 if the SCT passes validation.

SCT_LIST_validate() returns a negative integer if an internal error occurs, 0
if any of SCTs fails validation, or 1 if they all pass validation.

SCT_get_validation_status() returns the validation status of the SCT.
If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the
returned value will be SCT_VALIDATION_STATUS_NOT_SET.

=head1 SEE ALSO

L<ct(7)>

=head1 HISTORY

These functions were added in OpenSSL 1.1.0.

=head1 COPYRIGHT

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
56f3f714 RP	1	=pod
	2
	3	=head1 NAME
	4
	5	SCT_validate, SCT_LIST_validate, SCT_get_validation_status -
a0a9f36e	6	checks Signed Certificate Timestamps (SCTs) are valid
56f3f714 RP	7
	8	=head1 SYNOPSIS
	9
	10	#include <openssl/ct.h>
	11
ae97a654	12	typedef enum {
2947af32 BB	13	SCT_VALIDATION_STATUS_NOT_SET,
	14	SCT_VALIDATION_STATUS_UNKNOWN_LOG,
	15	SCT_VALIDATION_STATUS_VALID,
	16	SCT_VALIDATION_STATUS_INVALID,
	17	SCT_VALIDATION_STATUS_UNVERIFIED,
	18	SCT_VALIDATION_STATUS_UNKNOWN_VERSION
ae97a654 RP	19	} sct_validation_status_t;
ae97a654 RP	20
56f3f714 RP	21	int SCT_validate(SCT sct, const CT_POLICY_EVAL_CTX ctx);
56f3f714 RP	22	int SCT_LIST_validate(const STACK_OF(SCT) scts, CT_POLICY_EVAL_CTX ctx);
a0a9f36e	23	sct_validation_status_t SCT_get_validation_status(const SCT *sct);
56f3f714 RP	24
	25	=head1 DESCRIPTION
	26
a0a9f36e RP	27	SCT_validate() will check that an SCT is valid and verify its signature.
	28	SCT_LIST_validate() performs the same checks on an entire stack of SCTs.
	29	The result of the validation checks can be obtained by passing the SCT to
	30	SCT_get_validation_status().
56f3f714	31
a0a9f36e	32	A CT_POLICY_EVAL_CTX must be provided that specifies:
56f3f714	33
2f61bc2e	34	=over 2
a0a9f36e	35
2f61bc2e RS	36	=item *
	37
	38	The certificate the SCT was issued for.
a0a9f36e RP	39
	40	Failure to provide the certificate will result in the validation status being
	41	SCT_VALIDATION_STATUS_UNVERIFIED.
	42
2f61bc2e RS	43	=item *
	44
	45	The issuer of that certificate.
a0a9f36e RP	46
	47	This is only required if the SCT was issued for a pre-certificate
	48	(see RFC 6962). If it is required but not provided, the validation status will
	49	be SCT_VALIDATION_STATUS_UNVERIFIED.
56f3f714	50
2f61bc2e RS	51	=item *
	52
	53	A CTLOG_STORE that contains the CT log that issued this SCT.
56f3f714	54
a0a9f36e RP	55	If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
	56	status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.
	57
	58	=back
	59
	60	If the SCT is of an unsupported version (only v1 is currently supported), the
	61	validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION.
	62
1fa9ffd9 RP	63	If the SCT's signature is incorrect, its timestamp is in the future (relative to
	64	the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation
	65	status will be SCT_VALIDATION_STATUS_INVALID.
	66
	67	If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID.
a0a9f36e RP	68
	69	=head1 NOTES
	70
	71	A return value of 0 from SCT_LIST_validate() should not be interpreted as a
	72	failure. At a minimum, only one valid SCT may provide sufficient confidence
	73	that a certificate has been publicly logged.
56f3f714 RP	74
	75	=head1 RETURN VALUES
	76
a0a9f36e RP	77	SCT_validate() returns a negative integer if an internal error occurs, 0 if the
	78	SCT fails validation, or 1 if the SCT passes validation.
	79
	80	SCT_LIST_validate() returns a negative integer if an internal error occurs, 0
	81	if any of SCTs fails validation, or 1 if they all pass validation.
56f3f714	82
a0a9f36e RP	83	SCT_get_validation_status() returns the validation status of the SCT.
	84	If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the
	85	returned value will be SCT_VALIDATION_STATUS_NOT_SET.
56f3f714 RP	86
	87	=head1 SEE ALSO
	88
b97fdb57	89	L<ct(7)>
56f3f714	90
32fa3da8 RP	91	=head1 HISTORY
	92
	93	These functions were added in OpenSSL 1.1.0.
	94
56f3f714 RP	95	=head1 COPYRIGHT
	96
	97	Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
	98
	99	Licensed under the OpenSSL license (the "License"). You may not use
	100	this file except in compliance with the License. You can obtain a copy
	101	in the file LICENSE in the source distribution or at
	102	L<https://www.openssl.org/source/license.html>.
	103
6c3e9a71	104	=cut