RFC 8497
Marking SIP Messages to Be Logged
Pages: 46
Proposed Standard
Proposed Standard
Part 3 of 3 – Pages 31 to 46
5. Errors
5.1. Error Cases
The following error cases are possible for "log me" marking: 1. A "log me" marker is unexpectedly missing from a dialog that is being logged. 2. A "log me" marker unexpectedly appears in a dialog that is not being logged. 3. A "log me" marker unexpectedly disappears and then reappears in a dialog being logged. This is treated in the same way as case 1. 4. A "log me" marker is unexpectedly missing from a retransmission in a dialog being logged. This is treated in the same way as case 1. These cases apply to any request or response sent by any entity and in any direction in a dialog being "log me" marked. Detection of these error cases is described in this section.5.1.1. Missing "Log Me" Marker Error Case
Since "log me" marking is per-dialog, if a dialog is being marked and marking is missing from a request or response then this is an error. However, detecting such errors is not as simple as checking for missing markers because of cases such as non-supporting terminals where it is normal that marking is not done. Detecting errors must be evaluated separately for each neighbor. It is an error if a particular neighbor has previously sent "log me" in the dialog and then stops, independently of what has been happening with other neighbors. UAs and intermediaries that are stateless with respect to "log me" marking are not able detect such errors. User agents and intermediaries that are stateful with respect to "log me" marking are able to detect that a marker is missing from a dialog that has previously been "log me" marked. Error cases are illustrated in this section, and non-error cases in Section 5.2.1.
The following figures illustrate missing "log me" marker errors. Figure 8 shows an error detected at Proxy 1, where an expected "log me" marker is missing. [ NETWORK A ] [ NETWORK B ] Alice Proxy 1 Proxy 2 Bob | | | | | INVITE F1 | | | | (log me) | INVITE F2 | | |--------------->| (log me) | INVITE F3 | | |--------------->| (log me) | | | |--------------->| | | | | | | | 200 F4 | | | 200 F5 | (log me) | | 200 F6 | (log me) |<---------------| | (log me) |<---------------| | |<---------------| | | | | | | | ACK F7 | | | | (no log me) | | | |--------------->| | | | | ACK F8 | | | | (no log me) | | | |--------------->| | | | | ACK F9 | | | | (no log me) | | | |--------------->| Figure 8: Error Case: Missing "Log Me" Marker F1: Proxy 1 detects the "log me" marker and maintains state that this dialog is to be logged. F7: Proxy 1 detects that the expected "log me" marker is missing, considers it to be an error, and stops "log me" marking in subsequent requests and responses in this dialog. Figure 9 shows an error detected at both Proxy 2 and Bob's UA.
[ NETWORK A ] [ NETWORK B ] Alice Proxy 1 Proxy 2 Bob | INVITE F1 | | | | (log me) | | | |--------------->| | | | | INVITE F2 | | | | (log me) | | | |--------------->| | | | | | | | | | | 100 F3 | | | | (log me) | | | |<---------------| | | | | | INVITE F4 | | | | (log me) | | | 100 F5 |--------------->| | | (log me) | | | |<---------------| | | | | 180 F6 | | | | (log me) | | | |<---------------| | | 180 F7 | | | | (log me) | | | |<---------------| | | | | | | | | | | 180 F8 | | | | (log me) | | | |<---------------| | 200 F9 | | | | (log me) | | | 200 F10 |<---------------| | | (log me) | | | 200 F11 |<---------------| | | (log me) | | | |<---------------| | | | ACK F12 | | | | (no log me) | | | |--------------->| | | | | ACK F13 | | | | (no log me) | | | |--------------->| ACK F14 | | | | (no log me) | | | |--------------->| Figure 9: Error Case: Missing "Log Me" Marker
F2: Proxy 2 detects the "log me" marker and maintains state that
this dialog is to be logged.
F4: Bob's UA detects the "log me" marker and maintains state that
this dialog is to be logged.
F12: Proxy 1 detects that the expected "log me" marker is missing,
considers it to be an error, and stops "log me" marking in
subsequent requests and responses in this dialog. Hence, it
does not insert a "log me" marker in F13.
F13: Proxy 2 detects that the expected "log me" marker is missing,
considers it to be an error, and stops "log me" marking in
subsequent requests and responses in this dialog.
F14: Proxy 2 does not insert a "log me" marker because it has
stopped "log me" marking due to an error observed in F13.
Bob's UA detects that the expected "log me" marker is missing,
considers it to be an error, and stops "log me" marking in
subsequent requests and responses in this dialog.
5.1.2. "Log Me" Marker Appears Mid-dialog Error Case
SIP endpoints, intermediaries acting on behalf of endpoints, and B2BUAs that can perform "log me" marking are stateful. Such entities will expect a "log me" marker only for dialogs where the initial dialog-creating request was "log me" marked, either by themselves or by an upstream entity. "Log me" marking that subsequently begins mid-dialog is an error. Figure 10 illustrates a "log me" marking error observed in the middle of a dialog. Alice's UA supports "log me" marking but the call is not initially marked for logging, i.e., INVITE F1 is not "log me" marked. But Alice's UA starts to "log me" mark at the ACK request F7. Proxy 1 supports "log me" marking at the originating network boundary and therefore detects the error, does not log signaling, and removes the "log me" marker before forwarding the ACK request F8. [ NETWORK A ] [ NETWORK B ] Alice Proxy 1 Proxy 2 Bob | | | | | INVITE F1 | | | | (no log me) | INVITE F2 | | |--------------->| (no log me) | INVITE F3 | | |--------------->| (no log me) | | | |--------------->| | | | | | | | 200 F4 | | | 200 F5 | (no log me) | | 200 F6 | (no log me) |<---------------| | (no log me) |<---------------| | |<---------------| | | | | | | | ACK F7 | | | | (log me) | | | |--------------->| | | | | ACK F8 | | | | (no log me) | | | |--------------->| | | | | ACK F9 | | | | (log me) | | | |--------------->| Figure 10: Error Case: "Log Me" Marker Begins Mid-dialog
5.2. Non-error Cases
5.2.1. Missing "Log Me" Marker Non-error Case
The following figure illustrates a non-error case. Figure 11 shows Proxy 2 receiving a response with no "log me" marker that is not an error case. Proxy 2 is configured by network B to perform "log me" marking on behalf of Bob's UA, which does not support "log me" marking. Proxy 2 does not therefore expect responses from Bob to include a "log me" marker. [ NETWORK A ] [ NETWORK B ] Alice Proxy 1 Proxy 2 Bob | | | | | INVITE F1 | | | | (log me) | | | |--------------->| | | | | INVITE F2 | | | | (log me) | | | |--------------->| | | | | | | | | | | 100 F3 | | | | (log me) | | | |<---------------| | | | | | INVITE F4 | | | | (log me) | | | 100 F5 |--------------->| | | (log me) | | | |<---------------| | | | | 180 F6 | | | | (no log me) | | | |<---------------| | | 180 F7 | | | | (log me) | | | |<---------------| | | 180 F8 | | | | (log me) | | | |<---------------| | | Figure 11: Non-error Case: Missing "Log Me" Marker F2: Proxy 2 detects the "log me" marker and maintains state that this dialog is to be logged. Proxy 2 inserts "log me" markers on behalf of Bob's user agent, such as in F7.
F6: Proxy 2 detects that the "log me" marker is missing from the
response but considers "log me" marking to be ongoing as a
marker was not expected.
F7: Proxy 2 continues to "log me" mark requests and responses on
behalf of Bob's UA.
5.2.2. "Log Me" Marker Appears Mid-dialog Non-error Case
A SIP intermediary that can perform "log me" marking on behalf of an
endpoint MAY optionally mark a request or response towards a
non-supporting endpoint, such as the 100 response F3 in Figure 3. In
this case, the endpoint will receive a "log me" marker mid-dialog,
and this is not considered an error.
Another use case is a network in which some (but not all) endpoints
support "log me" marking and that wants to avoid treating endpoints
differently by always managing "log me" marking at a SIP
intermediary. In this case, the endpoint that supports "log me" is
not configured to mark a dialog; instead, the SIP intermediary is
configured to perform "log me" marking on behalf of that endpoint.
This case still requires authorization as described in Section 7.1.
This SIP intermediary MAY optionally mark a request or response
towards the endpoint, such as the 100 response F3 in Figure 3. The
endpoint will receive a "log me" marker mid-dialog, which is not
considered an error.
5.2.3. Combining Dialogs Non-error Case
When troubleshooting call flows that involve the SIP Join header
field specified in [RFC3911], the ideal scenario is to have "log me"
marking enabled on all UAs and intermediaries participating in the
end-to-end session. If the ideal scenario is not feasible, the
following rules apply:
o If an endpoint or an intermediary that is "log me" aware and is
already "log me" marking a dialog receives a SIP INVITE with a
Join header field and without a "log me" marker, it MUST NOT "log
me" mark responses and requests exchanged within the new dialog
established as a result of processing the SIP INVITE.
o If an endpoint or an intermediary that is "log me" aware and is
not "log me" marking a dialog receives a SIP INVITE with a Join
header field and with a "log me" marker, it MUST "log me" mark
responses and requests exchanged within the new dialog established
as a result of processing the SIP INVITE as per Section 4 of this
document.
5.3. Error Handling
The two error types that SIP entities must handle are defined in Section 5.1: a missing marker error and an error of "log me" marking that begins mid-dialog. Section 5.2 gives exceptions that have marking that begins mid-dialog or a missing marker but are not errors. If a missing marker error is detected by a UA, SIP intermediary, or B2BUA, it SHOULD consider this to be an error condition in the "log me" functionality. It MUST NOT mark subsequent requests and responses, and it MUST stop logging messages in the same dialog. Any previously logged messages SHOULD be retained, for the time period defined in Section 8.5, and not deleted. If a "log me" marking that begins mid-dialog error is detected by a UA, SIP intermediary, or B2BUA, it SHOULD consider this to be an error condition in the "log me" functionality. It MUST NOT forward the "log me" marker, and it MUST NOT log the message. It MUST NOT mark subsequent requests and responses, and it MUST NOT log subsequent messages in the same dialog. "Log me" marking errors can be detected and handled only by supporting UAs or B2BUAs. A SIP proxy as defined in [RFC3261] cannot detect or handle marking errors and will simply forward any "log me" marker it receives.6. Augmented BNF for the "logme" Parameter
ABNF is described in [RFC5234]. This document introduces a new "logme" parameter for the Session-ID header field defined in Section 5 of [RFC7989]. sess-id-param =/ logme-param logme-param = "logme" Figure 12: Augmented BNF for the "logme" Parameter
7. Security Considerations
7.1. "Log Me" Authorization
"Log me" marking MUST be disabled by default both at the endpoints and intermediaries and MUST be enabled only by authorized users. For example, an end user or network administrator must give permission for a terminal that supports "log me" marking in order to initiate marking. Similarly, a network administrator must enable a configuration at the SIP intermediary to perform "log me" marking on behalf of a terminal that does not support "log me" marking. The permission MUST be limited to only specific calls of interest that are originated in a given time duration. Activating a debug mode affects the operation of a terminal; therefore, the debugging configuration MUST be supplied by an authorized party to an authorized terminal through a secure communication channel.7.2. "Log Me" Marker Removal
The "log me" marker is not sensitive information, though it will sometimes be inserted because a particular device is experiencing problems. The presence of a "log me" marker will cause some SIP entities to log signaling messages. Therefore, this marker MUST be removed at the earliest opportunity if it has been incorrectly inserted, such as appearing mid-dialog in a dialog that was not being logged or outside the configured start and stop of logging. If SIP requests and responses are exchanged with an external network with which there is no agreement to pass "log me" marking, then the "log me" marking is removed as mandated in Section 3.4.2. This behavior applies to incoming and outgoing requests and responses.7.3. Denial-of-Service Attacks
Maliciously configuring a large number of terminals to simultaneously mark dialogs with a "log me" marker will cause high processor load on SIP entities that are logging signaling. Since "log me" marking is for the small number of dialogs subject to troubleshooting or regression testing, the number of dialogs that can be simultaneously logged can be statically limited without adversely affecting the usefulness of "log me" marking. Also, the SIP intermediary closest to the terminal and SIP intermediary at network edge (e.g., Session Border Controllers) can be configured to screen-out "log me" markers when troubleshooting or regression testing is not in progress.
7.4. Data Protection
A SIP entity that has logged information MUST protect the logs. Storage of the log files are subject to the security considerations specified in [RFC6872].8. Privacy Considerations
Logging includes all SIP header fields. The SIP privacy mechanisms defined in [RFC3323] can be used to ensure that logs do not divulge personal identity information in the core SIP header fields specified in [RFC3261]. Privacy mechanisms might also need to be applied to header fields defined by SIP extensions and for managing the confidentiality of the Request-URI and SIP header fields and bodies.8.1. Personal Identifiers
"Log me" marking is defined for the SIP protocol, and SIP has header fields such as From, Contact, and P-Asserted-Identity that can carry personal identifiers. Different protocol interactions can be correlated using the Session-ID and Call-ID header fields, but such correlation is limited to a single end-to-end session. In order to protect user privacy during logging, privacy settings can be enabled or requested by the terminal used by the end user. [RFC3323] suggests two mechanisms: o By using the value "anonymous" in the From header field o By requesting header-level and session-level privacy from SIP intermediaries using the Privacy header Endpoints that support Globally Routable User Agent URIs (GRUUs) can use a temporary GRUU (see Section 3.1.2 of [RFC5627]) assigned by the Registrar in order to protect user privacy as discussed in Section 10.3 of [RFC5627]. Intermediaries that perform "log me" marking on behalf of the endpoints (see Section 4.3) may also be configured to apply privacy (as defined in Section 3.3 of [RFC3323]) on messages that belong to a dialog that is "log me" marked. Complete anonymization (e.g., the Request-URI and the "username" field in the "o=" parameter of an SDP body) may not be possible in all circumstances; therefore, administrators of the originating and
terminating networks should consider how privacy will be ensured when providing consent for "log me" marking. "Log me" marking is typically used for troubleshooting and regression testing; in some cases, a service-provider-owned device with a dummy account can be used instead of a customer device. In such cases, no personal identifiers are included in the logged signaling messages.8.2. Data Stored at SIP Intermediaries
SIP endpoints and intermediaries that honor the "log me" request store all the SIP messages that are exchanged within a given dialog. SIP messages can contain the personal identifiers listed in Section 8.1 and additionally a user identity, calling party number, IP address, hostname, and other user-related or device-related items. The SIP message bodies describe the kind of session being set up by the identified end user and device. "Log me" marking does not introduce any additional user or device data to SIP but might indicate that a specific user is experiencing a problem. If the SIP SDP parameters [SDP-PARAMETERS] contain sensitive security information (e.g., encryption keys) such as "crypto" [RFC4568], 3GPP- Integrity-Key, or 3GPP-SRTP-Config [RFC6064] attributes, then the attribute value MUST be masked with a dummy value prior to storing the message in a log file. For example, the attribute value can be replaced with a string of special characters like "X", "*", and "#" as shown in the example below. a=crypto:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXX8.3. Data Visible at Network Elements
SIP messages that are logged due to "log me" requests are stored only by the SIP initiators, intermediaries, and recipients. Enablers as defined in Section 3.1 of [RFC6973], such as firewalls and DNS servers, do not log messages due to the "log me" marking.8.4. Preventing Fingerprinting
"Log me" functionality is typically used to troubleshoot a given problem and, hence, can be used as a method to identify users and devices that are experiencing issues. The best way to prevent fingerprinting of users is to enable or request SIP privacy for the logged dialog.
8.5. Retaining Logs
The lifetime of "log me" marking is equivalent to the lifetime of the dialog that initiated the "log me" request. When "log me" is extended to related dialogs, the lifetime is extended until there is no remaining related dialog for the end-to-end session. "Log me" automatically expires at the end of the dialog, and there is no explicit mechanism to turn off logging within a dialog. The scope of "log me" marking is limited, i.e., a user or the network administrator has to enable it on a per-session basis or for a specific time period. This minimizes the risk of exposing user data for an indefinite time. The retention time period for logged messages SHOULD be the minimum needed for each particular troubleshooting or testing case. The retention period is configured based on the data-retention policies of service providers and enterprises.8.6. User Control of Logging
Consent to turn on "log me" marking for a given session MUST be provided by the end user or by the network administrator. It is handled outside of the protocol through user interface or application programming interfaces at the endpoint, call control elements, and network management systems. Originating and terminating endpoints that are "log me" aware and have a user interface MUST indicate (using text, icon, etc.) to the user that a session is being logged. SIP entities across the communication path MAY be configured to pass through the "log me" marking but not honor the request, i.e., not log the data based on local policies.8.7. Recommended Defaults
The recommended defaults for "log me" marking are: o Turn on SIP privacy as described in Section 8 or use a device that is service provider owned with a dummy user identity for test calls. o Use the local UUID portion of the Session-ID header field value at the originating device as the test case identifier as described in Section 3.3.
9. IANA Considerations
9.1. Registration of the "logme" Parameter
The following parameter has been added to the "Header Field Parameters and Parameter Values" section of the "Session Initiation Protocol (SIP) Parameters" registry: +-------------+---------------+-------------------------+-----------+ | Header | Parameter | Predefined Values | Reference | | Field | Name | | | +-------------+---------------+-------------------------+-----------+ | Session-ID | logme | No (no values are | [RFC8497] | | | | allowed) | | +-------------+---------------+-------------------------+-----------+ Table 110. References
10.1. Normative References
[MEDIA-TYPES] IANA, "Media Types", <https://www.iana.org/assignments/media-types/>. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, DOI 10.17487/RFC3261, June 2002, <https://www.rfc-editor.org/info/rfc3261>. [RFC3323] Peterson, J., "A Privacy Mechanism for the Session Initiation Protocol (SIP)", RFC 3323, DOI 10.17487/RFC3323, November 2002, <https://www.rfc-editor.org/info/rfc3323>. [RFC3891] Mahy, R., Biggs, B., and R. Dean, "The Session Initiation Protocol (SIP) "Replaces" Header", RFC 3891, DOI 10.17487/RFC3891, September 2004, <https://www.rfc-editor.org/info/rfc3891>.
[RFC3911] Mahy, R. and D. Petrie, "The Session Initiation Protocol (SIP) "Join" Header", RFC 3911, DOI 10.17487/RFC3911, October 2004, <https://www.rfc-editor.org/info/rfc3911>. [RFC4538] Rosenberg, J., "Request Authorization through Dialog Identification in the Session Initiation Protocol (SIP)", RFC 4538, DOI 10.17487/RFC4538, June 2006, <https://www.rfc-editor.org/info/rfc4538>. [RFC4568] Andreasen, F., Baugher, M., and D. Wing, "Session Description Protocol (SDP) Security Descriptions for Media Streams", RFC 4568, DOI 10.17487/RFC4568, July 2006, <https://www.rfc-editor.org/info/rfc4568>. [RFC5627] Rosenberg, J., "Obtaining and Using Globally Routable User Agent URIs (GRUUs) in the Session Initiation Protocol (SIP)", RFC 5627, DOI 10.17487/RFC5627, October 2009, <https://www.rfc-editor.org/info/rfc5627>. [RFC6064] Westerlund, M. and P. Frojdh, "SDP and RTSP Extensions Defined for 3GPP Packet-Switched Streaming Service and Multimedia Broadcast/Multicast Service", RFC 6064, DOI 10.17487/RFC6064, January 2011, <https://www.rfc-editor.org/info/rfc6064>. [RFC6872] Gurbani, V., Ed., Burger, E., Ed., Anjali, T., Abdelnur, H., and O. Festor, "The Common Log Format (CLF) for the Session Initiation Protocol (SIP): Framework and Information Model", RFC 6872, DOI 10.17487/RFC6872, February 2013, <https://www.rfc-editor.org/info/rfc6872>. [RFC6873] Salgueiro, G., Gurbani, V., and A. Roach, "Format for the Session Initiation Protocol (SIP) Common Log Format (CLF)", RFC 6873, DOI 10.17487/RFC6873, February 2013, <https://www.rfc-editor.org/info/rfc6873>. [RFC7989] Jones, P., Salgueiro, G., Pearce, C., and P. Giralt, "End- to-End Session Identification in IP-Based Multimedia Communication Networks", RFC 7989, DOI 10.17487/RFC7989, October 2016, <https://www.rfc-editor.org/info/rfc7989>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. [SDP-PARAMETERS] IANA, "Session Description Protocol (SDP) Parameters", <https://www.iana.org/assignments/sdp-parameters/>.
10.2. Informative References
[RFC3665] Johnston, A., Donovan, S., Sparks, R., Cunningham, C., and K. Summers, "Session Initiation Protocol (SIP) Basic Call Flow Examples", BCP 75, RFC 3665, DOI 10.17487/RFC3665, December 2003, <https://www.rfc-editor.org/info/rfc3665>. [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/info/rfc5234>. [RFC5589] Sparks, R., Johnston, A., Ed., and D. Petrie, "Session Initiation Protocol (SIP) Call Control - Transfer", BCP 149, RFC 5589, DOI 10.17487/RFC5589, June 2009, <https://www.rfc-editor.org/info/rfc5589>. [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, July 2013, <https://www.rfc-editor.org/info/rfc6973>. [RFC7092] Kaplan, H. and V. Pascual, "A Taxonomy of Session Initiation Protocol (SIP) Back-to-Back User Agents", RFC 7092, DOI 10.17487/RFC7092, December 2013, <https://www.rfc-editor.org/info/rfc7092>. [RFC7206] Jones, P., Salgueiro, G., Polk, J., Liess, L., and H. Kaplan, "Requirements for an End-to-End Session Identification in IP-Based Multimedia Communication Networks", RFC 7206, DOI 10.17487/RFC7206, May 2014, <https://www.rfc-editor.org/info/rfc7206>. [RFC8123] Dawes, P. and C. Arunachalam, "Requirements for Marking SIP Messages to be Logged", RFC 8123, DOI 10.17487/RFC8123, March 2017, <https://www.rfc-editor.org/info/rfc8123>.
Acknowledgments
The authors wish to thank Paul Giralt, Paul Kyzivat, Jorgen Axell, Christer Holmberg, Vijay Gurbani, Ben Campbell, Gonzalo Salgueiro, Francesca Palombini, Adam Roach, Mirja Kuhlewind, Benjamin Kaduk, Eric Rescorla, Alissa Cooper, Warren Kumari, and Alexey Melnikov for their constructive review comments and guidance while developing this document.Authors' Addresses
Peter Dawes Vodafone Group The Connection Newbury, Berkshire RG14 2FN United Kingdom Phone: +44 7717 275009 Email: peter.dawes@vodafone.com Chidambaram Arunachalam Cisco Systems 7200-12 Kit Creek Road Research Triangle Park, NC 27709 United States of America Email: carunach@cisco.com