d060701
TROST
devNote
getpwd Platform Isolation
getpwd API Reference (0.50 alpha)
|
|
d060701
TROST
devNote |
0.50 2017-07-01 07:36 -0700 |
- The latest getpwd API Reference is available on the Internet at
<http://TROSTing.org/2006/07/d060701d.htm>.- This version, 0.50 alpha: <http://TROSTing.org/2006/07/d060701i.htm>. Consult that page for the latest status and for the most-recent electronic copies of this version of the specification.
Custom C/C++ Language function getpwd accepts entries from password fields, echoing "*" characters in place of the accepted characters.
1. Interface
2. Return Value
3. Required Header
4. Required Library
5. Dependencies
6. Failure Cases
7. Threat Model
8. Caveats
9. Bugs
int getpwd00(char buffer[], size_t maxpwd, size_t maxfield)
- buffer[] is an array of at least maxpwd char elements.
- maxpwd is the maximum number of char elements to deliver from the password entry (with additional entered characters ignored).
0 < maxpwd <= getpwdMAX_MAXPWD
- maxfield is the maximum number of "*" characters that will be echoed for entered characters; use 0 to suppress all echoing.
0 <= maxfield <= getpwdMAX_MAXFIELD < INT_MAX
is required.
- preprocessor-defined constant getpwdMAX_MAXPWD will never be less than 63. The value is fixed and will not change for any implementation of the same interface contract (i.e., getpwd00, getpwd10, etc).
- preprocessor-defined constant getpwdMAX_MAXFIELD will never be less than getpwdMAX_MAXPWD. The value is fixed and will not change for any implementation of the same interface contract (i.e., getpwd00 can vary from getpwd10, etc).
1.1 The maxfield and maxpwd parameters are independent. The function works correctly when maxfield > maxpwd and when backspace is entered at any time.
1.2 Only printable ASCII character codes are included in the password. Only includable characters are echoed. Password entry is ended by using the Enter key or otherwise producing a data-ending code according to conventions of the implementing platform (e.g., CR, LF, Ctrl-Z, Ctrl-D, or an EOF indication). Any other keyboard entries and their char codes are silently ignored. They do count against the limit of entered characters, however (section 6.1.3).
2.1 If getpwd is successful, the return value is the number of password char elements delivered in buffer[]. Unused positions up through buffer[maxpwd-1] are filled with null characters, '\0'. A zero return value signifies that no password was entered and that there are maxpwd null characters in buffer[].
2.2 The return value is less than 0 when getpwd fails (see 6, Failure Cases).
3.1 Place a copy of getpwd00.h into the folder containing the application source code, accessing the header definitions using C/C++ Language pre-processor command
#include "getpwd00.h"
3.2 It is useful to annotate the calling program with the specific versions of getpwd00.h that the program has been confirmed with and relied upon for the interface contract. E.g.,
#include "getpwd00.h"
/* assuming an interface contract compatible with
getpwd API Reference version 0.4 alpha */3.3 The header file defines
The function prototype for custom library function getpwd00
the pre-processor constant getpwdMAX_MAXPWD
the pre-processor constant getpwdMAX_MAXFIELD
There is no library for getpwd00. The getpwd00.h and getpwd00-version.c files should be included directly into a project directory for use in compiling the application that relies on getpwd00.
5.1 getpwd00.h only depends on Standard C library <stddef.h> (for size_t).
5.2 getpwd00-version.c depends on Standard C libraries and and on implementation-specific libraries (e.g., conio.h) for an assumed platform and compiler implementation. The version suffix in the file name specifies level of implementation and any platform/implementation-specific dependencies.
5.3 The getpwd00-version.c source programs provides preprocessor warnings and errors when the assumed implementation does not appear to be present during compilation.
5.4 Comments in the getpwd00-version.c code indicate how all dependencies are being relied upon and how they are used to satisfy the specifications of this custom function.
6.1 getpwd will return a less-than-zero failure value if any of the following conditions occur:
- 6.1.1 buffer is NULL
- 6.1.2 maxpwd is less than 1 or greater than getpwdMAX_MAXPWD; maxfield is greater than getpwdMAX_MAXFIELD.
- 6.1.3 There is a failure obtaining keyboard input, in displaying echo characters, or if the number of keyboard entries is some amount greater than 4 times the larger of maxpwd and maxfield. In these cases, buffer[0] to buffer[maxpwd-1] will contain null characters, '\0', in order to obliterate any accepted characters that were discarded.
6.2 There is no use of the Standard C/C++ errno value. There are no effects on the input-output state or error status of file and console streams. No exceptions are thrown by getpwd.
6.3 If there is keyboard entry of a control code that aborts operation on the implementation platform (e.g., Ctrl-C), the application will be immediately aborted in the usual way.
6.4 There is no protection against other threads accessing the console and even moving the character-output insertion point. Password elicitation should occur only when there is a single input-output-using thread operating in the application.
7.1 getpwd implementations only hold the char of the current input in local data. The full password, in clear, is assembled in buffer[]. There is no protection against a key logger attack. Protection of buffer[] against discovery is the responsibility of the application that uses getpwd.
7.2 Provided that maxpwd is valid, it is not possible to produce a buffer over-run using keyboard entries to getpwd. The limitation on amount of input mitigates against using unending responses to getpwd as a form of denial-of-service exploit.
7.3 There is no protection against simply failing to provide or end the input response. Any time-out protection and similar safeguards are the responsibility of the application that invokes the getpwd procedure.
7.4 Aborting the application while getpwd is eliciting input characters may leave any entered password characters exposed in buffer[].
7.5 getpwd is not suitable for protecting passwords that are entered over a non-secure network connection to the application.
8.1 maxfield should be chosen such that the string of *-echoes will not wrap onto the next line of the console display. If line wrapping occurs, the display may be corrupted and implementation of backspacing may fail to delete characters prior to the wrap.
8.2 Because getpwd operates directly from the console, it is not possible to provide a password response in a batch file (and that's generally a good thing). However, the operator may not detect that the application is waiting for keyboard input. If batch operation is allowable, it is important to ensure that a password prompt appears directly on the console regardless of how input and output might be redirected.
8.3 The names getpwd00-version.c are used to reflect implementation dependencies in the name of the file. This does not impact use of the implementation, because the name of the file and the name of the function are independent. The version of implemented interface contract (with 00 for alpha-level versions) does impact the name of the function. Samples in test releases of getpwd demonstrate practices for managing dependencies on alpha-level versions.
9.1 The correct handling of locale effects on the determination of char classes and recognition of control codes (e.g., for backspace and carriage-return) has not been reconciled in alpha versions of the code.
9.2 The correct handling of special keyboard entries (function keys, arrow keys, and special states) has not yet been verified.
9.3 No attempt has been made to provide any accommodation for reverse-direction (e.g., right-to-left) typing and display schemes. We are operating on the possibly-mistaken assumption that nothing special needs to be done at this level of console usage.
9.4 The implementation of preprocessor checks for the correct getpwd00-version.c platform and compiler implementation is not comprehensive in these alpha and beta versions.
|
created 2006-08-04-17:04 -0700 (pdt) by
orcmid |
You are navigating