.\" $OpenBSD: ASN1_time_parse.3,v 1.9 2020/11/02 17:45:35 tb Exp $
.\"
.\" Copyright (c) 2016 Bob Beck <beck@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: November 2 2020 $
.Dt ASN1_TIME_PARSE 3
.Os
.Sh NAME
.Nm ASN1_time_parse ,
.Nm ASN1_time_tm_cmp ,
.Nm ASN1_TIME_set_tm
.Nd LibreSSL utilities for ASN.1 time types
.Sh SYNOPSIS
.In openssl/asn1.h
.Ft int
.Fn ASN1_time_parse "const char *bytes" "size_t len" "struct tm *tm" "int mode"
.Ft int
.Fn ASN1_time_tm_cmp "struct tm *tm1" "struct tm *tm2"
.Ft ASN1_TIME *
.Fn ASN1_TIME_set_tm "ASN1_TIME *s" "struct tm *tm"
.Sh DESCRIPTION
The
.Fn ASN1_time_parse
function parses an ASN.1 time string of
.Ar len
bytes starting at
.Ar bytes .
The resulting time is stored in
.Ar tm
if
.Ar tm
is not
.Dv NULL .
.Pp
The
.Ar mode
parameter must be one of
.Bl -bullet -offset four
.It
0 to parse a time as specified in RFC 5280 for an X509 object,
which may be either a UTC time or a Generalized time.
.It
.Dv V_ASN1_UTCTIME
to parse an RFC 5280 format UTC time.
.It
.Dv V_ASN1_GENERALIZEDTIME
to parse an RFC 5280 format Generalized time.
.El
.Pp
The
.Fn ASN1_time_tm_cmp
function compares two times in
.Ar tm1
and
.Ar tm2 .
.Pp
The function
.Fn ASN1_TIME_set_tm
sets the
.Vt ASN1_TIME
structure
.Fa s
to the time represented by the
.Vt struct tm
value pointed to by
.Fa tm .
If
.Fa s
is
.Dv NULL ,
a new
.Vt ASN1_TIME
structure is allocated and returned.
.Sh RETURN VALUES
.Fn ASN1_time_parse
returns
.Bl -bullet -offset four
.It
-1 if the string was invalid for the
.Ar mode
specified.
.It
.Dv V_ASN1_UTCTIME
if the string parsed as a valid UTC time.
.It
.Dv V_ASN1_GENERALIZEDTIME
if the string parsed as a valid Generalized time.
.El
.Pp
.Fn ASN1_time_tm_cmp
returns
.Bl -bullet -offset four
.It
-1 if
.Ar tm1
is less than
.Ar tm2 .
.It
1 if
.Ar tm1
is greater than
.Ar tm2 .
.It
0 if
.Ar tm1
is the same as
.Ar tm2 .
.El
.Pp
.Fn ASN1_TIME_set_tm
returns a pointer to an
.Vt ASN1_TIME
structure or
.Dv NULL
if an error occurred.
.Sh SEE ALSO
.Xr ASN1_TIME_new 3 ,
.Xr ASN1_TIME_set 3 ,
.Xr X509_cmp_time 3
.Sh HISTORY
.Fn ASN1_time_parse
and
.Fn ASN1_time_tm_cmp
first appeared in
.Ox 6.1
and
.Fn ASN1_TIME_set_tm
in
.Ox 6.2 .