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:

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:

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:

UNIX has a asctime_r function similar to our asctime_s function. The differences are:

UNIX has a ctime_r function similar to our ctime_s function. the differences are:

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.