RFC 9410 PROPOSED STANDARD STIR · SIP · CALLER ID
STIR Identity Errors: Handling of Identity Header Errors for Secure Telephone Identity Revisited (STIR)
How STIR verification errors travel back to the signing side through the SIP Reason header when a call goes ahead anyway.
RFC EDITOR
Wendt, C., "Handling of Identity Header Errors for Secure Telephone Identity Revisited (STIR)", RFC 9410, DOI 10.17487/RFC9410, July 2023, <https://www.rfc-editor.org/info/rfc9410>.
BIBTEX
@misc{rfc9410,
series = {Request for Comments},
number = 9410,
howpublished = {RFC 9410},
publisher = {RFC Editor},
doi = {10.17487/RFC9410},
url = {https://www.rfc-editor.org/info/rfc9410},
author = {C. Wendt},
title = {{Handling of Identity Header Errors for Secure Telephone Identity Revisited (STIR)}},
pagetotal = 7,
year = 2023,
month = jul,
} RFC text
Contents
Internet Engineering Task Force (IETF) C. Wendt
Request for Comments: 9410 Somos Inc.
Category: Standards Track July 2023
ISSN: 2070-1721
Handling of Identity Header Errors for Secure Telephone Identity
Revisited (STIR)
Abstract
This document extends the current error-handling procedures for
mapping of verification failure reasons to 4xx codes for Secure
Telephone Identity Revisited (STIR) and the Authenticated Identity
Management in the Session Initiation Protocol (SIP). It extends the
ability to use the Reason header field as an option for conveying an
error associated with an Identity header field to the upstream
authentication service when local policy dictates that the call
should continue in the presence of a verification failure. This
document also defines procedures that enable a failure reason to be
mapped to a specific Identity header field for scenarios that use
multiple Identity header fields, where some may have errors and
others may not. The handling of those situations is also defined.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9410.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Revised BSD License text as described in Section 4.e of the
Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents
1. Introduction
2. Terminology
3. Reason Header Field Protocol "STIR"
4. Use of Provisional Response to Signal Errors without
Terminating the Call
5. Handling of a Verification Error When There Are Multiple
Identity Header Fields
6. Handling Multiple Verification Errors
7. Removal of the Reason Header Field by Authentication Service
8. IANA Considerations
9. Security Considerations
10. References
10.1. Normative References
10.2. Informative References
Acknowledgements
Author's Address
1. Introduction
The STIR framework as described in [RFC7340] is an authentication
framework for asserting a telephone number or URI-based identity
using a digital signature and certificate-based framework, as
described [RFC8225] and [RFC8226], respectively. [RFC8224] describes
the use of the STIR framework in the SIP protocol [RFC3261]. It
defines both a) the authentication service that creates a PASSporT
[RFC8225] and delivers it in an Identity header field, and b) the
verification service that correspondingly verifies the PASSporT and
embedded originating identity.
This document is concerned with errors in validating PASSporTs and
Identity header fields and how they are communicated in special
cases. This document also defines a solution to help address the
potential issue of multiple Identity header fields and the plurality
of potential verification errors. Additionally, it addresses the
issue of the current 4xx error response, i.e., the call is terminated
when a verification error is present. In some deployments, it may be
the case that the policy for handling errors dictates that calls
should continue even if there is a verification error. For example,
in many cases of inadvertent or operational errors that do not
represent any type of identity falsification attempt, the preferred
policy may be to continue the call despite the unverified identity.
In these cases, the authentication service should still be notified
of the error so that corrective action can be taken to fix any
issues. This specification will discuss the use of the Reason header
field in subsequent provisional (1xx) responses in order to deliver
the error back to the authentication service or other SIP path
network equipment responsible for error handling.
To handle multiple Identity header fields where some in a call may be
verified while others may not (i.e., they have errors), this document
defines a method by which an identifier is added to the header so
that the authentication service can uniquely identify which Identity
header field is being referred to in the case of an error.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. Reason Header Field Protocol "STIR"
This document defines a new Reason header field [RFC3326] protocol,
"STIR", for STIR applications using SIP as defined in [RFC8224]. The
use of "STIR" as a Reason header field protocol with the error
defined in [RFC8224] causes codes to allow the use of multiple Reason
header fields as detailed in [RFC3326] and updated in [RFC9366]. Any
provisional SIP response message or final response message, with the
exception of a 100 (Trying), MAY contain one or more Reason header
fields with a STIR-related cause code defined in [RFC8224] or future
specifications. The use of multiple Reason header fields is
discussed in more detail later in the document.
4. Use of Provisional Response to Signal Errors without Terminating the
Call
In cases where local policy dictates that a call should continue
regardless of any verification errors that may have occurred,
including 4xx errors described in Section 6.2.2 of [RFC8224], the
verification service MUST NOT send the 4xx as a response. Rather, it
should include the error response code and reason phrase in a Reason
header field in the next provisional or final response it sends to
the authentication service.
Example Reason header field:
Reason: STIR ;cause=436 ;text="Bad Identity Info"
5. Handling of a Verification Error When There Are Multiple Identity
Header Fields
In cases where a SIP message includes multiple Identity header fields
and one of those Identity header fields has an error, the
verification service MUST include the error response code and reason
phrase associated with the error in a Reason header field, defined in
[RFC3326], in the next provisional or final responses sent to the
authentication service. The reason cause in the Reason header field
MUST represent the error that occurred when verifying the contents of
the Identity header field. For a SIP INVITE containing multiple
Identity header fields, the "ppi" parameter for the Reason header
field is RECOMMENDED. As defined in [RFC8224], the STIR error codes
used in responses are based on an error associated with a specific
Identity header field representing a single error occurring with the
verification and processing of that Identity header field. The
association of a "ppi" parameter with a Reason header field [RFC3326]
using the protocol value of "STIR" defined in this document MUST only
identify a single cause code [RFC3326] in the context of a call
dialog [RFC3261] corresponding only to the STIR-related error codes
defined in [RFC8224] or future documents defining STIR-related error
codes. The associated PASSporT object can be included either in full
form or in compact form, where only the signature of the PASSporT is
included with two periods as a prefix, as defined in Section 7 of
[RFC8225], to identify the reported Identity header field with an
error. Compact form is the recommended form, as full form may
include information that could have privacy or security implications
in some call scenarios; this is discussed in Section 9.
Example Reason header field with a full form PASSporT:
Reason: STIR ;cause=436 ;text="Bad Identity Info" ;ppi= \
"eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1I \
joiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUub3JnL3Bhc3Nwb3J0LmNlciJ9.eyJ \
kZXN0Ijp7InVyaSI6WyJzaXA6YWxpY2VAZXhhbXBsZS5jb20iXX0sImlhdC \
I6IjE0NDMyMDgzNDUiLCJvcmlnIjp7InRuIjoiMTIxNTU1NTEyMTIifX0.r \
q3pjT1hoRwakEGjHCnWSwUnshd0-zJ6F1VOgFWSjHBr8Qjpjlk-cpFYpFYs \
ojNCpTzO3QfPOlckGaS6hEck7w"
Example Reason header field with a compact form PASSporT:
Reason: STIR ;cause=436 ;text="Bad Identity Info" ;ppi= \
"..rq3pjT1akEGjHCnWSwUnshd0-zJ6F1VOgFWSjHBr8Qjpjlk-cpFYpFYs \
ojNCpTzO3QfPOlckGaS6hEck7w"
6. Handling Multiple Verification Errors
If there are multiple Identity header field verification errors being
reported, the verification service MUST include a corresponding
number of Reason header fields per error. These Reason header fields
should include a "ppi" parameter, including the full or compact form
of the PASSporT with cause and text parameters identifying each
error. As mentioned previously, the potential use of multiple Reason
header fields defined in [RFC3326] is updated in [RFC9366], allowing
multiple Reason header fields with the same protocol value. For this
specification, "STIR" should be used for any STIR error defined in
[RFC8224] or future specifications.
Example Reason header fields for two identity info errors:
Reason: STIR ;cause=436 ;text="Bad Identity Info" ;ppi= \
"..rq3pjT1hoRwakEGjHCnWSwUnshd0-zJ6F1VOgFWSjHBr8Qjpjlk-cpFY \
pFYsojNCpTzO3QfPOlckGaS6hEck7w"
Reason: STIR ;cause=438 ;text="Invalid Identity Header" ;ppi= \
"..rJ6F1VOgFWSjHBr8Qjpjlk-cpFYpFYsq3pjT1hoRwakEGjHCnWSwUnsh \
d0-zckGaS6hEck7wojNCpTzO3QfPOl"
7. Removal of the Reason Header Field by Authentication Service
When an authentication service [RFC8224] receives the Reason header
field with a PASSporT it generated as part of an Identity header
field and the authentication of a call, it should first follow local
policy to recognize and acknowledge the error (e.g., perform
operational actions like logging or alarming). Then, it MUST remove
the identified Reason header field to avoid the PASSporT information
from going upstream to a User Agent Client (UAC) or User Agent Server
(UAS) that may not be authorized to see claim information contained
in the PASSporT for privacy or other reasons.
8. IANA Considerations
IANA has registered the following new protocol value (and associated
protocol cause) in the "Reason Protocols" registry under
<http://www.iana.org/assignments/sip-parameters>:
+================+=================+===========+
| Protocol Value | Protocol Cause | Reference |
+================+=================+===========+
| STIR | STIR Error code | [RFC8224] |
+----------------+-----------------+-----------+
Table 1
IANA has also registered a new header field parameter name in the
"Header Field Parameters and Parameter Values" registry under
<https://www.iana.org/assignments/sip-parameters>:
+==============+================+===================+===========+
| Header Field | Parameter Name | Predefined Values | Reference |
+==============+================+===================+===========+
| Reason | ppi | No | RFC 9410 |
+--------------+----------------+-------------------+-----------+
Table 2
9. Security Considerations
This specification discusses the use of a PASSporT as an identifier
for cases where there are multiple identity header field errors
occurring as part of the Reason header field response. For some call
scenarios (e.g., diversion-based call flows), the signer of the
PASSporT(s) may not be the first-hop initiator of the call. In those
cases, there may be some security or privacy concerns associated with
PASSporT information that is passed upstream beyond the
authentication service that originally signed the PASSporT(s) in the
resulting error Reason header field. This specification states that
the authentication service MUST remove the Reason header field with
the PASSporT to protect the security (e.g., use of a potentially
still-fresh PASSporT for replay attacks) and privacy of any potential
information that could be passed beyond the authentication service
response back in the direction of the call initiator. While this
specification allows for both the full and compact form of the
PASSporT to be used as the error identifier, use of the compact form
is RECOMMENDED to avoid the potential exposure of call information
contained in the full form of the PASSporT.
10. References
10.1. Normative References
[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>.
[RFC3326] Schulzrinne, H., Oran, D., and G. Camarillo, "The Reason
Header Field for the Session Initiation Protocol (SIP)",
RFC 3326, DOI 10.17487/RFC3326, December 2002,
<https://www.rfc-editor.org/info/rfc3326>.
[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>.
[RFC8224] Peterson, J., Jennings, C., Rescorla, E., and C. Wendt,
"Authenticated Identity Management in the Session
Initiation Protocol (SIP)", RFC 8224,
DOI 10.17487/RFC8224, February 2018,
<https://www.rfc-editor.org/info/rfc8224>.
[RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion
Token", RFC 8225, DOI 10.17487/RFC8225, February 2018,
<https://www.rfc-editor.org/info/rfc8225>.
[RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity
Credentials: Certificates", RFC 8226,
DOI 10.17487/RFC8226, February 2018,
<https://www.rfc-editor.org/info/rfc8226>.
[RFC9366] Sparks, R., "Multiple SIP Reason Header Field Values",
RFC 9366, DOI 10.17487/RFC9366, March 2023,
<https://www.rfc-editor.org/info/rfc9366>.
10.2. Informative References
[RFC7340] Peterson, J., Schulzrinne, H., and H. Tschofenig, "Secure
Telephone Identity Problem Statement and Requirements",
RFC 7340, DOI 10.17487/RFC7340, September 2014,
<https://www.rfc-editor.org/info/rfc7340>.
Acknowledgements
The author would like to thank David Hancock for help identifying
these error scenarios, as well as Jon Peterson, Roman Shpount, Robert
Sparks, Christer Holmberg, and others in the STIR Working Group for
their helpful feedback and discussion.
Author's Address
Chris Wendt
Somos Inc.
Email: chris-ietf@chriswendt.net
AI ELI5
On this page
PROBLEMWhen a STIR Identity check fails, the usual 4xx response ends the call, but some policies want the call to continue and still need the signing side told about the error, even with several Identity headers on one call.
MECHANISMA new Reason header protocol value, STIR, carries the error cause and text in a provisional or final response. A ppi parameter holding the PASSporT, preferably in compact form, says which Identity header failed.
WHY IT MATTERSThe authentication service learns of the error and can fix it, and it MUST remove the Reason header field before the response goes further upstream. The RFC is a Proposed Standard.
§1The Problem with Ending the Call
STIR lets a telephone number or URI-based identity be asserted with a digital signature. In SIP, an authentication service creates a PASSporT and delivers it in an Identity header field. A verification service checks it. The framework is described in RFC 7340 and its SIP use in RFC 8224.
RFC 8224 maps verification failures to 4xx responses, which end the call. In some deployments, policy says calls should continue even when verification fails, for instance after an inadvertent or operational error that is not an attempt at falsification. The authentication service should still hear about the error so that corrective action can be taken.
The document also addresses calls that carry several Identity header fields, where some verify and others do not.
Sometimes a guard lets someone in even though their badge scan failed. The badge office still needs to know the scan failed so it can fix the problem.
§4Reporting the Error Without Ending the Call
The document defines a new Reason header field protocol value, STIR. Any provisional or final SIP response except 100 (Trying) MAY contain one or more Reason header fields with a STIR-related cause code from RFC 8224 or future specifications.
When local policy says the call should continue despite a verification error, the verification service MUST NOT send the 4xx as a response. Instead it includes the error code and reason phrase in a Reason header field in the next provisional or final response to the authentication service.
Example: Reason: STIR ;cause=436 ;text="Bad Identity Info"
Instead of slamming the door, the checker lets the call through and quietly slips a note into the next reply saying what went wrong.
§5Pointing at the Right Identity Header
When a message has several Identity header fields and one has an error, the verification service MUST report the error in a Reason header field in the next provisional or final response. For a SIP INVITE with multiple Identity headers, a ppi parameter on the Reason header is RECOMMENDED. It names the failing Identity header by including its PASSporT.
The PASSporT can appear in full form or in compact form, where only the signature is included with two periods as a prefix. Compact form is recommended because full form may include information with privacy or security implications.
If several Identity headers fail, the verification service MUST include one Reason header field per error, each with cause, text and normally ppi. Sending several Reason headers with the same protocol value relies on the update in RFC 9366.
If a bag of tickets has a bad one, the note quotes the end of the bad ticket so the printer knows exactly which one to look at, without copying the whole ticket.
Reason header with compact PASSporT
Reason: STIR ;cause=436 ;text="Bad Identity Info" ;ppi= \
"..rq3pjT1akEGjHCnWSwUnshd0-zJ6F1VOgFWSjHBr8Qjpjlk-cpFYpFYs \
ojNCpTzO3QfPOlckGaS6hEck7w"§7Removal and Security
When the authentication service receives a Reason header field carrying a PASSporT it generated, it should first follow local policy, for example logging or alarming. Then it MUST remove that Reason header field, so the PASSporT does not travel upstream to a User Agent Client or Server that may not be authorized to see its claims.
The security section explains why. In some call flows, such as diversion-based ones, the signer may not be the first-hop initiator, so passing PASSporT data further could raise privacy or security concerns, including replay of a potentially still-fresh PASSporT. Compact form is RECOMMENDED to limit exposure.
The note quotes part of a ticket, so the ticket printer must tear it up after reading it. That way nobody else can see or reuse what was on it.
§8IANA Registrations
IANA registered two items. In the "Reason Protocols" registry it added protocol value STIR with protocol cause "STIR Error code", referencing RFC 8224. In the "Header Field Parameters and Parameter Values" registry it added the Reason header field parameter ppi, with no predefined values, referencing RFC 9410.
The two new words, STIR and ppi, were added to the official list of names so nobody uses them for something else.
§6References
[RFC8224]RFC 8224Peterson, J., Jennings, C., Rescorla, E., and C. Wendt, "Authenticated Identity Management in the Session Initiation Protocol (SIP)", RFC 8224, February 2018.February 2018[RFC8225]RFC 8225Wendt, C. and J. Peterson, "PASSporT: Personal Assertion Token", RFC 8225, February 2018.February 2018[RFC3326]RFC 3326Schulzrinne, H., Oran, D., and G. Camarillo, "The Reason Header Field for the Session Initiation Protocol (SIP)", RFC 3326, December 2002.December 2002[RFC9366]RFC 9366Sparks, R., "Multiple SIP Reason Header Field Values", RFC 9366, March 2023.March 2023[RFC3261]RFC 3261Rosenberg, J., et al., "SIP: Session Initiation Protocol", RFC 3261, June 2002.July 2002[RFC7340]RFC 7340Peterson, J., Schulzrinne, H., and H. Tschofenig, "Secure Telephone Identity Problem Statement and Requirements", RFC 7340, September 2014.September 2014