WG14 Document: N1059
Date: 2004-03-05
Security TR Editor's Report
State of Document
N1055 is a mixture of specific edits requested by the committee
at the last meeting, edits discussed in principle at the last
meeting, and new edits not previously discussed.
All new edits will be explicitly called to the reader's
attention by this editor's report.
In general, changes to the document are marked with change
bars in the margin. However, the change bars are not perfect
due to limitations of the tools used to produce the document
(or the workman using them). Sometimes the last line of a
changed multiline change will not be marked. Sometimes an extra
change bar will appear on an unchanged line above or below a
changed line. Some new footnotes do not have change bars.
The following changes are not in this draft:
- The description of the rand_s function has not been
updated with the requirements making it suitable for
cryptography.
- The Annex listing secure functions that should be used in
preference to insecure functions is missing.
- The Rationale is missing.
All subclause numbers in this report refer to N1055.
Major Changes
This section summarizes changes that potentially effect anyone
attempting to implement a secure library based on the last
draft.
__GOT_SECURE_LIB__
A conformance macro __GOT_SECURE_LIB__ was added. This macro is
defined by the headers in the TR if __USE_SECURE_LIB__ is
defined when the header is included. 3.1.1p2 defines the
semantics of __GOT_SECURE_LIB__. The introductory subclause for
each header defines it.
errno_t
The typedef errno_t with type int was added. errno_t is used
whenever a function return type or parameter deals with error
codes from errno.
This typedef is defined by errno.h and any header that needs
it (if __USE_SECURE_LIB__ is defined.).
Function prototypes were changed to use errno_t as
needed.
gets_s
Change the type of parameter n from int to size_t. This change
was not discussed at the last meeting, but was requested by two
implementers in email after the meeting.
RAND_MAX_S
The macro giving range of the rand_s function changed its name
from RAND_S_MAX to RAND_MAX_S. This change was not discussed at
the last meeting.
getenv_s
Add new parameter needed, which the function uses
to store the length of the string it wishes to return.
strlen_s, wcslen_s
Change the type of the maxsize argument from int to size_t.
Change the names of these functions to strnlen and wcsnlen.
Reason: these functions are not really replacements for strlen
and wcslen. There is no desire to tell programmers to replace
all calls to strlen with calls to strlen_s. But, the _s suffix
for these functions falsely give that impression. In contrast,
the "n" forms of the names give the right impression: these
functions are to be used in specific situations where
null-termination of input strings is problematic. (The
secure library does not attempt to do away with null-terminated
strings in favor of strings with a separate length.)
Renaming these functions was not discussed at the last
meeting.
asctime_s
The sample asctime_s was rewritten to use snprintf and not use
a local buffer for the string. A side-effect is that years with
more than four digits will work if the user provides a larger
buffer to store it.
scanf family
The scanf family functions (including the wide char versions)
now assign a value to all objects that were to be read into
when a matching failure or input failure occurs.
New functions
The following new functions were added:
- strcpy_s
- strcat_s
- wcscpy_s
- wcscat_s
- gmtime_r
- localtime_r
gmtime_r and localtime_r were not discussed at the previous
meeting.
The _r functions came from UNIX (see next section).
Should _s versions of the names also be added for
regularity?
Unix Compatibility
Most of the functions in the TR do not overlap with UNIX.
However, there are a few functions that do. I'll compare those
functions in the TR with functions in the Single UNIX
Specification.
A searchable version of the Open Group's Single Unix
Specification is available at:
http://www.unix-systems.org/single_unix_specification/
You may be asked to register (it's free) before you can load
that page.
The hyperlinks on function names in this section takes you
to the Single UNIX Specification man page for that
function.
UNIX has a
rand_r function. However, it does not appear to have the
same goals as our rand_s. It merely removes the static state of
the random number generator's seed.
UNIX has a
strtok_r function that is completely compatible with our
strtok_r function.
UNIX has a
strerror_r function that is very close to our strerror_r
function. The differences are:
- The arguments are in a different order.
- The specification fails to define the state of the output
buffer if there is not enough room for the error
message.
UNIX has a
asctime_r function similar to our asctime_s function. The
differences are:
- The arguments are in a different order, and UNIX lacks
the maxsize argument.
- The UNIX function returns a pointer to the string, not an
errno_t.
- The UNIX function returns a 26 char string. Our function
can return different-sized string depending upon the number
of digits in the year.
UNIX has a
ctime_r function similar to our ctime_s function. the
differences are:
- The arguments are in a different order, and UNIX lacks
the maxsize argument.
- The UNIX function returns a pointer to the string, not an
errno_t.
- The UNIX function returns a 26 char string. Our function
can return different-sized string depending upon the number
of digits in the year.
UNIX has a
gmtime_r function that is completely compatible with our
gmtime_r function.
UNIX has a
localtime_r function that is completely compatible with our
localtime_r function.
Non-standard functions
It appears that OpenBSD has two functions, strlcpy and strlcat,
that are similar to our strcpy_s and strcat_s. However, the BSD
functions return a length, not an error code, and truncate if
there is too little space. See: http://www.courtesan.com/todd/papers/strlcpy.html
Change Log
The remainder of this document is a per-subclause list of all
changes to N1055 since N1031.
2. Normative references
Para 2, the reference to TC1, was added.
3.1.1 Standard Headers
Para 1, extra "only" deleted.
Para 2, __GOT_SECURE_LIB__ was added.
3.2 errno.h
New subclause because of errno_t. This header was not in the
last draft.
3.3 stdio.h
Para 2, define __GOT_SECURE_LIB__.
Para 3, define errno_t.
3.3.1.1 The tmpnam_s function
Use errno_t in prototype.
Footnote 2. Add discussion of race condition and
interprogram conflicts. Are there other issues needing
discussion?
Para 4, Footnote 3. Allow tmpnam to call tmpnam_s.
3.3.2.1 The fscanf_s function
Para 2, Para 4, Footnote 5. Require a failing fscanf_s to
assign a value to all objects that were to be read into.
3.3.3.1 The gets_s function
Change the type of parameter n from int to size_t. This change
was not discussed at the last meeting.
Para 2, Para 4, Para 5. Define the behavior if n is
zero.
3.4 stdlib.h
Para 2. Define __GOT_SECURE_LIB__. Change name of RAND_S_MAX to
RAND_MAX_S.
Para 3. Define errno_t.
3.4.1.1 The rand_s function
Para 2, 5. Change name of RAND_S_MAX to RAND_MAX_S.
3.4.2.1 The getenv_s function
Add new parameter needed, which the function uses
to store the length of the string it wishes to return.
Para 2-4. Describe use of needed.
Issue: Should there be an errno value to distinguish a
missing environment variable as opposed to output buffer was
not big enough?
3.4.3 Searching and sorting utilities
Para 3. "shall not alter the contents of the array." becomes
"shall not alter the contents of either the array or search
key."
Para 3. Add "but shall not otherwise alter the contents of
any individual element."
Footnote 7, "are always nonzero" becomes "are always valid
and nonzero".
Issue: Microsoft has found lots of code that sorts or
searches zero-length arrays (sometimes pointed to by a null
pointer). An implementation is free to permit this as an
extension, but should searching/sorting zero-length arrays
added to this TR?
3.4.3.1 The bsearch_s function
Footnote 8. "is sorted" becomes "has been sorted".
3.4.3.2 The qsort_s function
Para 4. "their order" becomes "their relative order"
3.5 string.h
Para 1-3. Define __GOT_SECURE_LIB__ and errno_t.
3.5.1.1 The memcpy_s function
Use errno_t for return type.
3.5.1.2 The memmove_s function
Use errno_t for return type.
3.5.1.3 The strcpy_s function
New function.
3.5.1.4 The strncpy_s function
Use errno_t for return type.
Para 2. Don't mention return value here.
Para 4. Add "successive"
3.5.2.1 The strcat_s function
New function.
3.5.2.2 The strncat_s function
Use errno_t for return type.
Various paragraphs. Typeset m in italic.
Para 3. Don't mention return value here.
Para 5. Add "successive"
Para 9. Use the phrase "will contain the sequence" (used
elsewhere in the Standard).
3.5.4.1 The strerror_s function
Use errno_t for return type and for type of parameter errnum.
Para 3. Add word "desired".
3.5.4.2 The strnlen function
Change the name of the function from strlen_s.
Change the type of the maxsize argument from int to
size_t.
Para 3. Add last sentence.
3.6 time.h
Para 1-3. Define __GOT_SECURE_LIB__ and errno_t.
3.6.1 Components of time
Para 1. Define normalized. Note that the Standard defines the
"normal ranges" for struct tm members.
3.6.2 Time conversion functions
Para 1. Remove extra comma.
3.6.2.1 The asctime_s function
Use errno_t for return type.
Para 2. Add word "normalized".
The sample asctime_s was rewritten to use snprintf.
Para 3. Rewrite since the result is not tied to a 26 char
buffer.
Add footnote 20.
3.6.2.2 The ctime_s function
Use errno_t for return type.
Para 3. Rewrite since the result is not tied to a 26 char
buffer.
Add footnote 21.
3.6.2.3 The gmtime_r function
New function.
3.6.2.4 The localtime_r function
New function.
3.7 wchar.h
Para 1-3. Define __GOT_SECURE_LIB__ and errno_t.
3.7.1.1 The fwscanf_s function
Para 2, Para 4, Footnote 23. Require a failing fwscanf_s to
assign a value to all objects that were to be read into.
3.7.2.1.1 The wcscpy_s function
New function.
3.7.2.1.2 The wcsncpy_s function
Use errno_t for return type.
Para 2. Don't mention return value here.
Para 4. Add "successive"
3.7.2.1.3 The wmemcpy_s function
Use errno_t for return type.
Para 2. Add "successive"
3.7.2.1.4 The wmemmove_s function
Use errno_t for return type.
Para 2. Add "successive"
3.7.2.2.1 The wcscat_s function
New function.
3.7.2.2.2 The wcsncat_s function
Use errno_t for return type.
Various paragraphs. Typeset m in italic.
Para 3. Don't mention return value here.
Para 5. Add "successive"
Para 8. Use the phrase "will contain the sequence" (used
elsewhere in the Standard).
3.7.2.3.1 The wcsnlen function
Change the name of the function from wcslen_s.
Change the type of the maxsize argument from int to
size_t.
Para 3. Add last sentence.