Network Working Group|
Request for Comments: 2593
NEC Europe Ltd.
This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited.
Copyright © The Internet Society (1999). All Rights Reserved.
The IETF Script MIB defines an interface for the delegation of management functions based on the Internet management framework. A management script is a set of instructions that are executed by a language specific runtime system. The Script MIB extensibility protocol (SMX) defined in this memo separates language specific runtime systems from language independent Script MIB implementations.
2. Process Model and Communication Model
3. Security Profiles
4. Start of Runtime Systems and Connection Establishment
5. SMX Messages
5.1 Common Definitions
6. Elements of Procedure
6.1 SMX Message Processing on the Runtime Systems
6.1.1 Processing the `hello' Command
6.1.2 Processing the `start' Command
6.1.3 Processing the `suspend' Command
6.1.4 Processing the `resume' Command
6.1.5 Processing the `abort' Command
6.1.6 Processing the `status' Command
6.1.7 Generation of Asynchronous Notifications
6.2 SMX Message Processing on the SNMP Agent
6.2.1 Creating a Runtime System
6.2.2 Generating the `hello' Command
6.2.3 Generating the `start' Command
6.2.4 Generating the `suspend' Command
6.2.5 Generating the `resume' Command
6.2.6 Generating the `abort' Command
6.2.7 Generating the `status' Command
6.2.8 Processing Asynchronous Notifications
7. An Example SMX Message Flow
8. Security Considerations
11. Authors' Addresses
12. Full Copyright Statement
The Script MIB  defines a standard interface for the delegation of management functions based on the Internet management framework. In particular, it provides the following capabilities:
A management script is a set of instructions executed by a language specific runtime system. The Script MIB does not prescribe a specific language. Instead, it allows to control scripts written in different languages that are executing concurrently.
The Script MIB Extensibility protocol (SMX) defined in this memo can be used to separate language specific runtime systems from the runtime system independent Script MIB implementations. The lightweight SMX protocol can be used to support different runtime systems without any changes to the language neutral part of a Script MIB implementation.
Examples of languages and runtime systems considered during the design of the SMX protocol are the Java virtual machine  and the Tool Command Language (Tcl) . Other languages with comparable
features should be easy to integrate as well.
Figure 1 shows the process and communication model underlying the SMX protocol. The language and runtime system independent SNMP agent implementing the Script MIB communicates with one ore more runtime systems via the SMX protocol. A runtime system may be able to execute one or multiple scripts simultaneously (multi-threading). The SMX protocol supports multi-threading, but it does not require multi- threaded runtime systems.
The SMX protocol uses a local storage device (usually implemented on top of the local file system) to transfer scripts from the SNMP agent to the runtime systems. The SNMP agent has read and write access to the script storage device while the runtime systems only need read access. The SMX protocol passes the location of a script in the local storage device to the runtime engines. It is then the responsibility of the runtime engines to load the script from the specified location.
+--------------+ SMX +---------+ | |<-------------->| O O O |<-+ SNMP | Script MIB | +---------+ | <---------->| | | | SNMP Agent | runtime 2 | | | SMX +---------+ | | |<-------------->| O | | +--------------+ +---------+ | ^ ^ | | +---------+ | | | | script |----------+ | +------>| storage |------------------+ +---------+
Figure 1: SMX process and communication model
Security profiles control what a running script is allowed to do. It is useful to distinguish two different classes of security profiles:
- The operating system security profile specifies the set of operating system services that can be used by the operating system level process which executes a script. Under UNIX, this maps to the effective user and group identity for the running
process. In addition, many UNIX versions allow to set other resource limits, such as the number of open files or the maximum stack sizes. Another mechanism in UNIX is the chroot() system call which changes the file system root for a process. The chroot() mechanism can be used to prevent runtime systems from accessing any system files. It is suggested to make use of all applicable operating system security mechanism in order to protect the operating system from malicious scripts or runtime systems.
- Secure runtime systems provide fine grained control over the set of services that can be used by a running script at a particular point during script execution. A runtime security profile specifying fine grained access control is runtime system dependent. For a Java virtual machine, the runtime security profile is interpreted by the SecurityManager and ClassLoader classes. For Tcl, the runtime security profile maps to the interpreter's security profile .
The SMX protocol allows to execute scripts under different operating system profiles and runtime system profiles. Multiple operating system security profiles are realized by using multiple runtime systems which execute in operating system processes with different security profiles. Multiple runtime security profiles are supported by passing a security profile name to a runtime system during script invocation.
The Script MIB does not define how operating system or runtime system security profiles are identified. This memo suggests that the smLaunchOwner is mapped to an operating system security profile and a runtime system security profile when a script is started.
The SNMP agent starts runtime systems based on the static properties of the runtime system (multi-threaded or single-threaded) and the operating system security profiles. Starting a new runtime system requires to create a process environment which matches the operating system security profile.
The SNMP agent initially passes information to the runtime system by means of environment variables. The information is needed to establish a trusted communication channel between the SNMP agent and a runtime system.
The SNMP agent first creates a listening TCP socket which accepts connections from runtime systems. It is the responsibility of the runtime system to establish a connection to this TCP socket once it
has been started. The port number of the listening TCP socket is passed from the SNMP agent to the runtime system in the environment variable SMX_PORT.
The SNMP agent must ensure that only authorized runtime systems establish a connection to the listening TCP socket. The following rules are used for this purpose:
- The TCP connection must originate from the local host. - The SNMP agent queries the runtime system for a security cookie and closes the TCP connection if no valid response is received within a given time interval. The security cookie is a random number generated by the SNMP agent and passed to the runtime system as part of its environment. The cookie is found in the environment variable SMX_COOKIE.
The security assumption here is that access to the process environment is protected by the operating system.
Alternate transports (e.g. UNIX domain sockets) are possible but not defined at this point in time. The reason to choose TCP as the transport protocol for SMX was that TCP is supported by all potential runtime systems, while other transports are not universally available.
The message formats described below are defined using the Augmented BNF (ABNF) defined in RFC 2234 . The definitions for `ALPHA', `DIGIT', `HEXDIG', `WSP', `CRLF', `CR', `LF', `HTAB', `VCHAR' and `DQUOTE' are imported from appendix A of RFC 2234 and not repeated here.
The following ABNF definitions are used in subsequent sections to define the SMX protocol messages.
Zero = %x30 ; the ASCII character '0' AlNum = DIGIT / ALPHA / %x2D-2F ; digits, alphas plus '-', '.', '/' QuotedString = DQUOTE *(VCHAR / WSP) DQUOTE HexString = 1*(HEXDIG HEXDIG)
Id = 1*DIGIT ; identifier for an SMX transaction Script = QuotedString ; script file name RunId = 1*DIGIT ; globally unique identifier for a ; running script (note, smRunIndex ; is only unique for a smLaunchOwner, ; smLaunchName pair) Profile = 1*AlNum ; security profile name RunState = "1" ; smRunState `initializing' RunState =/ "2" ; smRunState `executing' RunState =/ "3" ; smRunState `suspending' RunState =/ "4" ; smRunState `suspended' RunState =/ "5" ; smRunState `resuming' RunState =/ "6" ; smRunState `aborting' RunState =/ "7" ; smRunState `terminated' ExitCode = "1" ; smRunExitCode `noError' ExitCode =/ "2" ; smRunExitCode `halted' ExitCode =/ "3" ; smRunExitCode `lifeTimeExceeded' ExitCode =/ "4" ; smRunExitCode `noResourcesLeft' ExitCode =/ "5" ; smRunExitCode `languageError' ExitCode =/ "6" ; smRunExitCode `runtimeError' ExitCode =/ "7" ; smRunExitCode `invalidArgument' ExitCode =/ "8" ; smRunExitCode `securityViolation' ExitCode =/ "9" ; smRunExitCode `genericError' Cookie = HexString ; authentication cookie Version = "SMX/1.0" ; current version of the SMX protocol Argument = HexString / QuotedString ; see smRunArgument Result = HexString / QuotedString ; see smRunResult ErrorMsg = HexString / QuotedString ; see smRunError
The definition of QuotedString requires further explanation. A quoted string may contain special character sequences, all starting with the backslash character (%x5C). The interpretation of these sequences is as follows:
`\\' backslash character (`%x5C') `\t' tab character (`HTAB') `\n' newline character (`LF') `\r' carriage-return character (`CR') `\"' quote character (`DQUOTE')
In all other cases not listed above, the backslash is dropped and the following character is treated as an ordinary character. `Argument' and `Result' is either a QuotedString or a HexString. The Script MIB defines script arguments and results as arbitrary octet strings. The SMX protocol supports a binary and a human readable representation since it is likely that printable argument and result strings will be used frequently. However, an implementation must be able to handle both formats in order to be compliant with the Script MIB.
The `Cookie' is a HexString which does not carry any semantics other than being a random sequence of bytes. It is therefore not necessary to have a human readable representation.
The following ABNF definitions define the set of SMX commands which can be sent from the SNMP agent to a runtime system.
Command = "hello" WSP Id CRLF Command =/ "start" WSP Id WSP RunId WSP Script WSP Profile WSP Argument CRLF
Command =/ "suspend" WSP Id WSP RunId CRLF
Command =/ "resume" WSP Id WSP RunId CRLF
Command =/ "abort" WSP Id WSP RunId CRLF
Command =/ "status" WSP Id WSP RunId CRLF
The `hello' command is always the first command sent over a SMX connection. It is used to identify and authenticate the runtime system. The `start' command starts the execution of a script. The `suspend', `resume' and `abort' commands can be used to change the status of a running script. The `status' command is used to retrieve status information for a running script.
There is no compile command. It is the responsibility of the SNMP agent to perform any compilation steps as needed before using the SMX `start' command. There is no SMX command to shutdown a runtime system. Closing the connection must be interpreted as a request to
terminate all running scripts in that runtime system and to shutdown the runtime system.
Every reply message starts with a three digit reply code and ends with `CRLF'. The three digits in a reply code have a special meaning. The first digit identifies the class of a reply message. The following classes exist:
1yz transient positive response 2yz permanent positive response 3yz transient negative response 4yz permanent negative response 5yz asynchronous notification
The classes 1yz and 3yz are currently not used by SMX version 1.0. They are defined only for future SMX extensions.
The second digit encodes the specific category. The following categories exist:
x0z syntax errors that don't fit any other category x1z replies for commands targeted at the whole runtime system x2z replies for commands targeted at scripts x3z replies for commands targeted at running instances of scripts
The third digit gives a finer gradation of meaning in each category specified by the second digit. Below is the ABNF definition of all reply messages and codes:
Reply = "211" WSP Id WSP Version WSP Cookie CRLF ; identification of the ; runtime system
Reply =/ "231" WSP Id WSP RunState CRLF
; status of a running script Reply =/ "232" WSP Id CRLF ; abort of a running script Reply =/ "401" WSP Id CRLF ; syntax error in command Reply =/ "402" WSP Id CRLF ; unknown command Reply =/ "421" WSP Id CRLF ; unknown or illegal Script Reply =/ "431" WSP Id CRLF ; unknown or illegal RunId
Reply =/ "432" WSP Id CRLF ; unknown or illegal Profile Reply =/ "433" WSP Id CRLF ; illegal Argument Reply =/ "434" WSP Id CRLF ; unable to change the status of ; a running script
Reply =/ "511" WSP Zero WSP QuotedString CRLF
; an arbitrary message send from ; the runtime system
Reply =/ "531" WSP Zero WSP RunId WSP RunState CRLF
; asynchronous running script ; status change
Reply =/ "532" WSP Zero WSP RunId WSP RunState WSP Result CRLF
; intermediate script result
Reply =/ "533" WSP Zero WSP RunId WSP RunState WSP Result CRLF
; intermediate script result that ; trigger an event report
Reply =/ "534" WSP Zero WSP RunId WSP Result CRLF
; normal script termination
Reply =/ "535" WSP Zero WSP RunId WSP ExitCode WSP ErrorMsg CRLF
; abnormal script termination.
This section describes in detail the processing steps performed by the SNMP agent and the runtime system with regard to the SMX protocol.
This section describes the processing of SMX command messages by a runtime engine and the conditions under which asynchronous notifications are generated.
When the runtime system receives a message, it first tries to recognize a command consisting of the command string and the transaction identifier. If the runtime system is not able to extract both the command string and the transaction identifier, then the message is discarded. An asynchronous `511' reply may be generated in this case. Otherwise, the command string is checked to be valid, i.e. to be one of the strings `hello', `start', `suspend', `resume', `abort', or `status'. If the string is invalid, a `402' reply is
sent and processing of the message stops. If a valid command has been detected, further processing of the message depends on the command as described below.
The command specific processing describes several possible syntax errors for which specific reply messages are generated. If the runtime engine detects any syntax error which is not explicitely mentioned or which cannot be identified uniquely, a generic `401' reply is sent indicating that the command cannot be executed.
When the runtime system receives a `hello' command, it processes it as follows:
When the runtime system receives a `start' command, it processes it as follows:
(a) The syntax of the `RunId' parameter is checked and a `431' reply is sent if any syntax error is detected. (b) The syntax of the `Script' parameter is checked and a `421' reply is sent if any syntax error is detected. (c) The syntax of the `Profile' parameter is checked and a `432' reply is sent if any syntax error is detected. (d) If syntax of the `Argument' parameter is checked and a `433' reply is sent if any syntax error is detected.
Processing of the `start' command stops, when the script reaches the state `running'. For each asynchronous state change of the running script, a `531' reply is sent. Processing of the `start' command is also stopped if an error occurs before the state `running' is reached. In this case, the run is aborted and a `535' reply is generated.
If an `abort' command or a `suspend' command for the running script is received before processing of the `start' command is complete, then the processing of the `start' command may be stopped before the state `running' is reached. In this case, the resulting status of the running script is given by the respective reply to the `abort' or `suspend' command, and no reply with the transaction identifier of the `start' command is generated.
When the runtime system receives a `suspend' command, it processes it as follows:
When the runtime system receives a `resume' command, it processes it as follows:
When the runtime system receives an `abort' command, it processes it as follows:
When the runtime system receives a `status' command, it processes it as follows:
The runtime system generates or may generate the following notifications:
This section describes the conditions under which an SNMP agent implementing the Script MIB generates SMX commands. It also describes how the SNMP agent processes replies to SMX commands.
New runtime systems are started by the SNMP agent while processing set requests for a `smLaunchStart' variable. The SNMP agent first searches for an already running runtime systems which matches the security profiles associated with the `smLaunchStart' variable. If no suitable runtime system is available, a new runtime system is started by preparing the environment for the new runtime system and starting the executable for the runtime system in a new process which conforms to the operating system security profile. The SNMP agent prepares to accept a connection from the new runtime system. The `smRunState' of all scripts that should be executed in this new runtime system is set to `initializing'.
The `hello' command is generated once a connection request from a runtime system has been accepted. The SNMP agent sends the `hello' command as defined in section 5.2. The SNMP agent then expects a reply from the runtime system within a reasonable timeout interval.
The `start' command is generated while processing set-requests for a `smLaunchStart' variable. The `start' command assumes that the SNMP agent already determined a runtime system suitable to execute the script associated with the `smLaunchStart' variable. The SNMP agent sends the `start' command as defined in section 5.2 to the selected runtime system. The SNMP agent then expects a reply from the runtime system within a reasonable timeout interval.
The `suspend' command is generated while processing set-requests for the `smLaunchControl' and `smRunControl' variables which change the value to `suspend'. The SNMP agent sets the `smRunState' variable to `suspending' and sends the `suspend' command as defined in section 5.2. The SNMP agent then expects a reply from the runtime system within a reasonable timeout interval.
The `resume' command is generated while processing set-requests for the `smLaunchControl' and `smRunControl' variables which change the value to `resume'. The SNMP agent sets the `smRunState' variable to `resuming' and sends the `resume' command as defined in section 5.2. The SNMP agent then expects a reply from the runtime system within a reasonable timeout interval.
The `abort' command is generated while processing set-requests for the `smLaunchControl' and `smRunControl' variables which change the value to `abort'. In addition, the `abort' command is also generated if the `smRunLifeTime' variable reaches the value 0. The SNMP agent sends the `abort' command as defined in section 5.2. The SNMP agent then expects a reply from the runtime system within a reasonable timeout interval.
The `status' command is generated either periodically or on demand by the SNMP agent in order to retrieve status information from running scripts. The SNMP agent sends the `status' command as defined in 5.2. The SNMP agent then expects a reply from the runtime system within a reasonable timeout interval.
`terminated', the `smRunExitCode' to `genericError' and the `smRunError' is modified to describe the error situation.
The runtime system can send asynchronous status change notifications. These `5yz' replies are processed as described below.
`terminated' and `smExitCode' and `smRunError' are updated.
Below is an example SMX message exchange. Messages send from the SNMP agent are marked with `>' while replies send from the runtime system are marked with `<'. Line terminators (`CRLF') are not shown in order to make the example more readable.
> hello 1
< 211 1 SMX/1.0 0AF0BAED6F877FBC > start 2 42 "/var/snmp/scripts/foo.jar" untrusted "" > start 5 44 "/var/snmp/scripts/bar.jar" trusted "www.ietf.org" < 231 2 2 > start 12 48 "/var/snmp/scripts/foo.jar" funny "" < 231 5 2 < 532 0 44 2 "waiting for response" > status 18 42 > status 19 44 < 432 12 < 231 19 2 < 231 18 2 > hello 578 < 211 578 SMX/1.0 0AF0BAED6F877FBC > suspend 581 42 < 231 581 4 < 534 0 44 "test completed" > abort 611 42 < 232 611
The SMX protocol runs on top of a local TCP connection. Protocol messages never leave the local system. It is therefore not possible to attack the message exchanges if the underlying operating system protects local TCP connections from other users on the same machine.
The only critical situation is the connection establishment phase. The rules defined in section 4 ensure that only local connections are accepted and that a runtime system has to identify itself with a security cookie generated by the SNMP agent and passed to the runtime system process as part of its environment. This rule ensures that scripts will only be executed on authorized runtime systems. This scheme relies on the protection of process environments by the operating system. Well maintained UNIX operating systems have this property.
The SMX protocol allows to execute script under different operating system and runtime system security profiles. The memo suggests to map the smLaunchOwner value to an operating system and a runtime system security profile. The operating system security profile is enforced by the operating system by setting up a proper process environment. The runtime security profile is enforced by a secure runtime system (e.g. the Java virtual machine or a safe Tcl interpreter) .
The protocol described in this memo is the result of a joint project between the Technical University of Braunschweig and C&C Research Laboratories of NEC Europe Ltd. in Berlin. We would like to thank the following project members for their contributions to the initial design and the implementation of the protocol described in this memo:
M. Bolz (TU Braunschweig) C. Kappler (NEC Europe Ltd.) A. Kind (NEC Europe Ltd.) S. Mertens (TU Braunschweig) J. Nicklisch (NEC Europe Ltd.)
 Levi, D. and J. Schoenwaelder, "Definitions of Managed Objects for the Delegation of Management Scripts", RFC 2592, May 1999.
 Lindholm, T., and F. Yellin, "The Java Virtual Machine Specification", Addison Wesley, 1997.
 J.K. Ousterhout, "Tcl and the Tk Toolkit", Addison Wesley, 1994.
 Fritzinger, J.S., and M. Mueller, "Java Security", White Paper, Sun Microsystems, Inc., 1996.
 Levy, J.Y., Demailly, L., Ousterhout, J.K., and B. Welch, "The Safe-Tcl Security Model", Proc. USENIX Annual Technical Conference, June 1998.
 Crocker, D., and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd., November 1997.
 Schoenwaelder, J., and J. Quittek, "Secure Management by Delegation within the Internet Management", Proc. IFIP/IEEE International Symposium on Integrated Network Management '99, May 1999.
Phone: +49 531 391-3283
NEC Europe Ltd.
C&C Research Laboratories
Phone: +49 30 254230-19
Copyright © The Internet Society (1999). All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Funding for the RFC Editor function is currently provided by the Internet Society.