diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2015-02-03 01:31:33 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2015-02-03 16:47:57 +0000 |
commit | a724e79ed761ea535a6c7457c90da5ff4b1cea69 (patch) | |
tree | 041cbbb5ed6dacfebde025f8d112f9f51655b336 /doc | |
parent | 3d47c1d331fdc7574d2275cda1a630ccdb624b08 (diff) | |
download | openssl-a724e79ed761ea535a6c7457c90da5ff4b1cea69.tar.gz |
Preliminary ASN1_TIME documentation.
Reviewed-by: Rich Salz <rsalz@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/ASN1_TIME_set.pod | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/doc/crypto/ASN1_TIME_set.pod b/doc/crypto/ASN1_TIME_set.pod new file mode 100644 index 0000000000..ae2b53d355 --- /dev/null +++ b/doc/crypto/ASN1_TIME_set.pod @@ -0,0 +1,129 @@ +=pod + +=head1 NAME + +ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string, +ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions. + +=head1 SYNOPSIS + + ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t); + ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, + int offset_day, long offset_sec); + int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); + int ASN1_TIME_check(const ASN1_TIME *t); + int ASN1_TIME_print(BIO *b, const ASN1_TIME *s); + + int ASN1_TIME_diff(int *pday, int *psec, + const ASN1_TIME *from, const ASN1_TIME *to); + +=head1 DESCRIPTION + +The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the +time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME +structure is allocated and returned. + +ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented +by the time B<offset_day> and B<offset_sec> after the time_t value B<t>. +The values of B<offset_day> or B<offset_sec> can be negative to set a +time before B<t>. The B<offset_sec> value can also exceed the number of +seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated +and returned. + +ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time +represented by string B<str> which must be in appropriate ASN.1 time +format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). + +ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>. + +ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable +format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example +"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time +structure has invalid format it prints out "Bad time value" and returns +an error. + +ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between +B<from> and B<to>. If B<to> represents a time later than B<from> then +one or both (depending on the time difference) of B<*pday> and B<*psec> +will be positive. If B<to> represents a time earlier than B<from> then +one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from> +represent the same time then B<*pday> and B<*psec> will both be zero. +If both B<*pday> and B<*psec> are non-zero they will always have the same +sign. The value of B<*psec> will always be less than the number of seconds +in a day. If B<from> or B<to> is NULL the current time is used. + +=head1 NOTES + +The ASN1_TIME structure corresponds to the ASN.1 structure B<Time> +defined in RFC5280 et al. The time setting functions obey the rules outlined +in RFC5280: if the date can be represented by UTCTime it is used, else +GeneralizedTime is used. + +The ASN1_TIME structure is represented as an ASN1_STRING internally and can +be freed up using ASN1_STRING_free(). + +The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt +is made to correct ancient calendar changes (for example from Julian to +Gregorian calendars). + +Some applications add offset times directly to a time_t value and pass the +results to ASN1_TIME_set() (or equivalent). This can cause problems as the +time_t value can overflow on some systems resulting in unexpected results. +New applications should use ASN1_TIME_adj() instead and pass the offset value +in the B<offset_sec> and B<offset_day> parameters instead of directly +manipulating a time_t value. + +=head1 BUGS + +ASN1_TIME_print() currently does not print out the time zone: it either prints +out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT +anyway. + +=head1 EXAMPLES + +Set a time structure to one hour after the current time and print it out: + + #include <time.h> + #include <openssl/asn1.h> + ASN1_TIME *tm; + time_t t; + BIO *b; + t = time(NULL); + tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); + b = BIO_new_fp(stdout, BIO_NOCLOSE); + ASN1_TIME_print(b, tm); + ASN1_STRING_free(tm); + BIO_free(b); + +Determine if one time is later or sooner than the current time: + + int day, sec; + + if (!ASN1_TIME_diff(&day, &sec, NULL, to)) + /* Invalid time format */ + + if (day > 0 || sec > 0) + printf("Later\n"); + else if (day < 0 || sec < 0) + printf("Sooner\n"); + else + printf("Same\n"); + +=head1 RETURN VALUES + +ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure +or NULL if an error occurred. + +ASN1_TIME_set_string() returns 1 if the time value is successfully set and +0 otherwise. + +ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0 +otherwise. + +ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if +an error occurred (I/O error or invalid time format). + +ASN1_TIME_diff() returns 1 for sucess and 0 for failure. It can fail if the +pass ASN1_TIME structure has invalid syntax for example. + +=cut |