```
INTERNET-DRAFT                                                Jens Sabitzer
Expires: March 19, 2025                               September 19, 2024

                 Standard API Password Change Interface (SAPI)
                         for Password Change Procedures
                    draft-sabitzer-sapi-password-change-00

Intended status: Standards Track

Status of This Memo

   This Internet-Draft is submitted in full conformance with the provisions of 
   BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering Task 
   Force (IETF), its areas, and its working groups.  Note that other groups 
   may also distribute working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months 
   and may be updated, replaced, or obsoleted by other documents at any 
   time.  It is inappropriate to use Internet-Drafts as reference material 
   or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   https://www.ietf.org/1id-abstracts.html

   The list of Internet-Draft Shadow Directories can be accessed at
   https://www.ietf.org/shadow.html

   This Internet-Draft will expire on March 19, 2025.

Copyright Notice

   Copyright (c) 2024 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 Simplified BSD License text as described in Section 4.e of 
   the Trust Legal Provisions and are provided without warranty as described 
   in the Simplified BSD License.

Abstract

   This document proposes a standardized set of API endpoints for securely
   changing user passwords, using a unique identifier prefix to ensure
   compatibility and avoid conflicts with other APIs. As the number of
   online accounts continues to grow, managing passwords has become
   increasingly challenging. Even with the use of password managers, the
   process of updating passwords-whether due to a security breach,
   expiration, or other reasons-remains a time-consuming and manual task.
   Currently, there is no standardized method for performing password changes
   across various platforms, which further complicates this process. The goal
   of this proposal is to establish a universal standard for password change
   processes, enabling password managers and services to automate password
   updates with minimal configuration, thereby reducing the burden on users
   and improving overall security.

1. Introduction

   Passwords are central to user authentication, and securely managing password 
   changes is critical for protecting user accounts. This RFC defines a 
   standardized API, the Standard API Password Interface (SAPI), to handle 
   password changes in a secure and consistent way. The structure of the API is 
   designed to work seamlessly with password managers, allowing to automate
   password changes while adhering to security best practices.

1.1. Key Goals:

   1. Consistency: Ensure all systems follow the same structure and format for 
      password changes.
   2. Security: Implement secure transmission, validation, and storage of passwords.
   3. Adoptability: Keep the API simple, with clear requirements (MUST, SHOULD, 
      MAY) to encourage broad adoption.

2. API Overview

2.1. API Endpoints

   Two primary API endpoints are proposed under the `sapi-password` prefix:

   1. Compliance Check Endpoint: Confirms that the system adheres to the standard 
      for password changes.
   2. Password Change Request Endpoint: Handles the actual password change request.

2.2. API Authentication

   All API calls MUST be authenticated using OAuth 2.0 with appropriate scopes 
   for password changes. API keys or other bearer tokens MAY be used as alternative 
   authentication mechanisms.

3. API Endpoints

3.1. Compliance Check

3.1.1. Endpoint: `/sapi-password/v1/compliance`

   This endpoint verifies that a system complies with the standard password change 
   process and provides details on the password policy (e.g., length and complexity 
   requirements).

   - Method: GET
   - Response:
     - 200 OK: Compliance confirmed.
     - 400 Bad Request: Non-compliance or unsupported features.
   - Request Headers:
     - Authorization: Bearer <token> (OAuth 2.0 or API key)

3.1.2. Example Request:
```
GET /sapi-password/v1/compliance HTTP/1.1
Host: example.com
Authorization: Bearer abcd1234
```

3.1.3. Example Response:
```json
{
  "compliance": true,
  "min_length": 8,
  "max_length": 128,
  "complexity_requirements": {
    "uppercase": true,
    "lowercase": true,
    "numbers": true,
    "special_characters": true
  },
  "min_number_uppercase": 1,
  "min_number_lowercase": 1,
  "min_number_numbers": 1,
  "min_number_special_characters": 1,
  "allowed_special_characters": "!@#$%^&*"
}
```

3.2. Password Change Request

3.2.1. Endpoint: `/sapi-password/v1/change`

   This endpoint handles the password change request, ensuring that the process 
   adheres to the password complexity and security requirements defined by the 
   system.

   - Method: POST
   - Request Body (JSON):

     - current_password (string, required): The user's current password. MUST
     - new_password (string, required): The new password the user wishes to set. MUST
     - user_id (string, optional): The user's unique identifier in the system
       (if applicable). SHOULD

   - Response:
     - 200 OK: Password changed successfully.
     - 400 Bad Request: Invalid input (e.g., current password incorrect, password 
       fails complexity check).
     - 401 Unauthorized: Authentication failure.
     - 429 Too Many Requests: Rate limiting due to excessive attempts.

   - Request Headers:
     - Authorization: Bearer <token> (OAuth 2.0 or API key)
     - Content-Type: application/json

3.2.2. Example Request:
```
POST /sapi-password/v1/change HTTP/1.1
Host: example.com
Authorization: Bearer abcd1234
Content-Type: application/json

{
  "current_password": "oldPassword123!",
  "new_password": "newPassword456!",
  "user_id": "user12345"
}
```

3.2.3. Example Response (Success):
```json
{
  "message": "Password changed successfully",
  "suggested_next_password_rotation_days": 90
}
```

3.2.4. Example Response (Failure - Complexity):
```json
{
  "error_msg": "Password complexity requirements not met"
}
```

4. Security Considerations

4.1. API Authentication

   All API requests MUST be authenticated using modern authentication scheme like 
   OAuth 2.0 OpenID or API tokens. The Authorization header MUST be used for secure 
   transmission of these tokens.

4.2. Secure Transmission

   All API requests MUST be sent over HTTPS. Requests over unencrypted channels 
   (e.g., HTTP) MUST be rejected with a 403 Forbidden status.

4.3. Rate Limiting

   Systems MUST implement rate limiting to prevent brute force attacks. A minimum 
   cooldown period of 1 minute between password change attempts SHOULD be enforced, 
   and the system MAY implement a lockout mechanism after failed attempts.

5. IANA Considerations

   This document has no IANA considerations.

6. References

6.1. Normative References

   - [RFC 6749] OAuth 2.0 Authorization Framework, D. Hardt, October 2012.
   - [RFC 7617] The 'Basic' HTTP Authentication Scheme, J. Reschke, September 2015.

Author's Address

   Jens Sabitzer
   Email: jens_sabitzer@hotmail.de
```