Certificate Management - CSMS Developer Guide

{
  "iso15118SchemaVersion": "string (max 50)",
    // REQUIRED - Schema version for the 15118 session between EV and CS.
    // Needed for parsing the EXI stream.

  "action": "Install | Update",
    // REQUIRED - For M01, this will be "Install".

  "exiRequest": "string (max 11000)",
    // REQUIRED - Raw CertificateInstallationReq from EV, Base64 encoded.
    // Min supported length: 11000.
    // Configurable via OCPPCommCtrlr.FieldLength

  "maximumContractCertificateChains": "integer (>= 0)",
    // (2.1) ABSENT during ISO 15118-2 session.
    // REQUIRED during ISO 15118-20 session.
    // Maximum number of contracts the EV wants to install.

  "prioritizedEMAIDs": ["string (max 255)", ...],
    // (2.1) ABSENT during ISO 15118-2. OPTIONAL during ISO 15118-20.
    // EMAIDs for which contract certificates must be requested first.
    // Min: 1, Max: 8 items
}

{
  "status": "Accepted | Failed",
    // REQUIRED - Whether the message was processed properly.

  "statusInfo": {                    // OPTIONAL
    "reasonCode": "string (max 20)",
    "additionalInfo": "string (max 1024)"
  },

  "exiResponse": "string (max 17000)",
    // REQUIRED - Raw CertificateInstallationRes for the EV, Base64 encoded.
    // Min supported length: 17000.
    // Configurable via OCPPCommCtrlr.FieldLength

  "remainingContracts": "integer (>= 0)"
    // (2.1) Number of contracts that can be retrieved with additional
    // requests. Used for ISO 15118-20 multi-contract flow.
}

HANDLE Get15118EVCertificateRequest(request):
    ASSERT request.action == "Install"

    // 1. Parse the EXI request
    //    Use request.iso15118SchemaVersion to determine the correct parser

    // 2. Forward to Contract Certificate Pool / secondary actor
    //    The CSMS is responsible for forwarding the CertificateInstallationRequest
    //    to the appropriate backend (e.g., contract certificate pool per VDE-AR-E 2802-100-1)

    // 3. Determine ISO 15118 version from presence of maximumContractCertificateChains
    IF request.maximumContractCertificateChains IS PRESENT:
        // ISO 15118-20 session
        isISO15118_20 = true
    ELSE:
        // ISO 15118-2 session
        isISO15118_20 = false

    // 4. For ISO 15118-20: Handle multi-contract flow
    IF isISO15118_20:
        // Fetch contracts from all Contract Certificate Pools
        // Respect prioritizedEMAIDs ordering if present
        // Return first CertificateInstallationRes + total remainingContracts
        response.remainingContracts = totalAvailableContracts - 1

        // The CS will send additional Get15118EVCertificateRequest messages
        // as long as remainingContracts > 0 (see req M01.FR.06)
        // Each subsequent response MUST decrease remainingContracts by 1 (req M01.FR.07)

    // 5. Build response
    response.status = "Accepted"  // or "Failed" if processing failed
    response.exiResponse = base64EncodedCertificateInstallationRes

    RETURN response

HANDLE Get15118EVCertificateRequest(request):
    IF request.action == "Update":
        // Forward to the secondary actor (contract certificate pool)
        // which will process the CertificateUpdateRequest
        // The CSMS is responsible for forwarding it to the appropriate backend

        response.status = "Accepted"
        response.exiResponse = base64EncodedCertificateUpdateRes
        RETURN response

    IF request.action == "Install":
        // Handle as M01 (see above)

{
  "certificateType": [
    "V2GRootCertificate" | "MORootCertificate" | "CSMSRootCertificate" |
    "V2GCertificateChain" | "ManufacturerRootCertificate" | "OEMRootCertificate"
  ]
    // OPTIONAL - Types of certificates requested.
    // When OMITTED, ALL certificate types are requested.
    // Min: 1 item
}

{
  "status": "Accepted | NotFound",
    // REQUIRED - Accepted = matching certificates found.
    // NotFound = no matching certificates.

  "statusInfo": {                    // OPTIONAL
    "reasonCode": "string (max 20)",
    "additionalInfo": "string (max 1024)"
  },

  "certificateHashDataChain": [      // OPTIONAL (present when status = Accepted)
    {
      "certificateType": "V2GRootCertificate | MORootCertificate | ...",
        // REQUIRED

      "certificateHashData": {       // REQUIRED - CertificateHashDataType
        "hashAlgorithm": "SHA256 | SHA384 | SHA512",
        "issuerNameHash": "string (max 128)",
        "issuerKeyHash": "string (max 128)",
        "serialNumber": "string (max 40)"
      },

      "childCertificateHashData": [  // OPTIONAL - Max 4 items
        {                            // Sub-CAs under a root
          "hashAlgorithm": "SHA256 | SHA384 | SHA512",
          "issuerNameHash": "string (max 128)",
          "issuerKeyHash": "string (max 128)",
          "serialNumber": "string (max 40)"
        }
      ]
    }
  ]
}

FUNCTION retrieveInstalledCertificates(chargingStationId, certificateTypes):
    // 1. Build the request
    request = new GetInstalledCertificateIdsRequest()
    IF certificateTypes IS NOT EMPTY:
        request.certificateType = certificateTypes
    // If certificateTypes is empty/null, omit the field to get ALL types

    // 2. Send to Charging Station
    response = sendToChargingStation(chargingStationId, request)

    // 3. Handle response
    IF response.status == "Accepted":
        FOR EACH chain IN response.certificateHashDataChain:
            // Store certificate hash data for later use
            // (e.g., for DeleteCertificateRequest)
            storeCertificateInfo(
                chargingStationId,
                chain.certificateType,
                chain.certificateHashData,
                chain.childCertificateHashData  // may be null
            )
    ELSE IF response.status == "NotFound":
        // No matching certificates found on the Charging Station
        log("No certificates of requested type found on station " + chargingStationId)

    RETURN response

{
  "certificateHashData": {           // REQUIRED - CertificateHashDataType
    "hashAlgorithm": "SHA256 | SHA384 | SHA512",
      // REQUIRED - CSMS MUST use the SAME hashAlgorithm that the CS uses
      // to report the certificate in GetInstalledCertificateIdsResponse
      // (req M04.FR.07)

    "issuerNameHash": "string (max 128)",
      // REQUIRED - Hash of the issuer's distinguished name (DN),
      // calculated over the DER encoding of the issuer's name field.

    "issuerKeyHash": "string (max 128)",
      // REQUIRED - Hash of the DER encoded public key (value only,
      // excluding tag and length) of the subject public key field
      // in the issuer's certificate.

    "serialNumber": "string (max 40)"
      // REQUIRED - Hex string of the serial number,
      // without '0x' prefix and without leading zeroes.
  }
}

{
  "status": "Accepted | Failed | NotFound",
    // REQUIRED - Result of the delete operation.

  "statusInfo": {                    // OPTIONAL
    "reasonCode": "string (max 20)",
    "additionalInfo": "string (max 1024)"
  }
}

FUNCTION deleteCertificate(chargingStationId, certificateHashData):
    // IMPORTANT: Before deleting, the CSMS SHOULD verify:

    // 1. DO NOT delete the Charging Station Certificate via this message.
    //    Deletion of the Charging Station Certificate is NOT allowed via
    //    DeleteCertificateRequest (req M04.FR.06). The CS will respond with Failed.

    // 2. Be VERY careful deleting the last/all CSMSRootCertificates.
    //    If all CSMSRootCertificates are deleted, the CS will NOT be able to
    //    connect to any CSMS (cannot validate server certificate).
    //    ADVISED: Confirm this is truly intended before proceeding.

    // 3. Use the SAME hashAlgorithm the CS reported in
    //    GetInstalledCertificateIdsResponse (req M04.FR.07)

    request = new DeleteCertificateRequest()
    request.certificateHashData = certificateHashData

    response = sendToChargingStation(chargingStationId, request)

    SWITCH response.status:
        CASE "Accepted":
            // Certificate was successfully deleted
            // Note: If deleted cert was a sub-CA or root, the CS MAY also
            //   delete all child certificates (req M04.FR.08)
            removeCertificateFromLocalStore(chargingStationId, certificateHashData)

        CASE "Failed":
            // Deletion failed. Possible reasons:
            //   - Certificate is the Charging Station Certificate (not deletable)
            //   - CS rejected deletion (last one of its type)
            //   - Internal CS error
            log("Delete failed: " + response.statusInfo?.reasonCode)

        CASE "NotFound":
            // Certificate not found on the Charging Station
            log("Certificate not found on station " + chargingStationId)

    RETURN response

{
  "certificateType": "V2GRootCertificate | MORootCertificate |
    ManufacturerRootCertificate | CSMSRootCertificate | OEMRootCertificate",
    // REQUIRED - Type of certificate being installed.

  "certificate": "string (max 10000)"
    // REQUIRED - PEM encoded X.509 certificate.
}

{
  "status": "Accepted | Rejected | Failed",
    // REQUIRED - Result of the installation.

  "statusInfo": {                    // OPTIONAL
    "reasonCode": "string (max 20)",
    "additionalInfo": "string (max 1024)"
  }
}

FUNCTION installCACertificate(chargingStationId, certificateType, pemCertificate):
    request = new InstallCertificateRequest()
    request.certificateType = certificateType
    request.certificate = pemCertificate

    response = sendToChargingStation(chargingStationId, request)

    SWITCH response.status:
        CASE "Accepted":
            // Certificate successfully installed in the CS trust store
            // If it was already present, CS replaces it (req M05.FR.17)
            storeCertificateRecord(chargingStationId, certificateType, pemCertificate)

        CASE "Rejected":
            // Installation rejected. Possible reasons:
            //   - CertificateEntries.maxLimit would be exceeded (req M05.FR.06)
            //   - Certificate is invalid (req M05.FR.07)
            //   - For CSMSRootCertificate with AdditionalRootCertificateCheck=true:
            //     new cert is NOT signed by the old CSMS Root (req M05.FR.11)
            log("Install rejected: " + response.statusInfo?.reasonCode)

        CASE "Failed":
            // Installation failed due to internal CS error
            log("Install failed: " + response.statusInfo?.reasonCode)

    RETURN response

FUNCTION rotateCSMSRootCertificate(chargingStationId, newCertPEM):
    // req M05.FR.09: Only one CSMSRootCertificate can be installed at a time
    //   (plus a temporary fallback)

    // req M05.FR.10: The new CSMS Root certificate SHALL replace the old one
    //   AND the new Root Certificate MUST be signed by the old Root Certificate

    // req M05.FR.11: If NOT signed by old root -> CS responds Rejected

    // req M05.FR.12: If signed by old root -> CS installs new cert AND
    //   temporarily keeps old cert as fallback, responds Accepted

    // req M05.FR.13: After CS successfully reconnects using the new cert ->
    //   CS removes the old (fallback) certificate

    // req M05.FR.14: If CS cannot verify CSMS server cert with new root ->
    //   CS tries the old (fallback) root certificate

    response = installCACertificate(chargingStationId, "CSMSRootCertificate", newCertPEM)

    IF response.status == "Accepted":
        // The CS now has both old and new CSMS root certs temporarily
        // On next successful TLS connection with new cert, old is removed
        // CSMS should ensure its server certificate is signed by the new root

{
  "ocspRequestData": {               // REQUIRED - OCSPRequestDataType
    "hashAlgorithm": "SHA256 | SHA384 | SHA512",
      // REQUIRED

    "issuerNameHash": "string (max 128)",
      // REQUIRED - Hash of the issuer's distinguished name (DN), DER encoded.

    "issuerKeyHash": "string (max 128)",
      // REQUIRED - Hash of the DER encoded public key of the issuer.

    "serialNumber": "string (max 40)",
      // REQUIRED - Hex serial number without '0x' prefix or leading zeroes.

    "responderURL": "string (max 2000)"
      // REQUIRED - OCSP responder URL (case insensitive).
      // REQUIRED in OCPP (optional in ISO 15118).
  }
}

{
  "status": "Accepted | Failed",
    // REQUIRED - Whether the CSMS was successful in retrieving the OCSP status.
    // Does NOT indicate the validity of the certificate itself.

  "statusInfo": {                    // OPTIONAL
    "reasonCode": "string (max 20)",
    "additionalInfo": "string (max 1024)"
  },

  "ocspResult": "string (max 18000)"
    // OCSPResponse class per IETF RFC 6960, DER encoded then Base64 encoded.
    // MAY only be omitted when status is not Accepted.
    // Min supported length: 18000.
    // Configurable via OCPPCommCtrlr.FieldLength
}

HANDLE GetCertificateStatusRequest(request):
    ocspData = request.ocspRequestData

    // 1. Build OCSP request per RFC 6960 using the provided hash data
    ocspRequest = buildOCSPRequest(
        hashAlgorithm: ocspData.hashAlgorithm,
        issuerNameHash: ocspData.issuerNameHash,
        issuerKeyHash: ocspData.issuerKeyHash,
        serialNumber: ocspData.serialNumber
    )

    // 2. Send OCSP request to the responder URL
    TRY:
        ocspResponse = httpPost(ocspData.responderURL, ocspRequest)

        // 3. Format response per requirements:
        //    - OCSPResponse per IETF RFC 6960 (req M06.FR.08)
        //    - Formatted according to ASN.1 [X.680] (req M06.FR.08)
        //    - DER encoded (req M06.FR.09)
        //    - Then Base64 encoded for transmission
        derEncoded = ocspResponse.toDER()
        base64Result = base64Encode(derEncoded)

        response.status = "Accepted"      // req M06.FR.02
        response.ocspResult = base64Result // req M06.FR.03

    CATCH error:
        // OCSP retrieval failed
        response.status = "Failed"         // req M06.FR.04
        response.statusInfo = {
            reasonCode: "OCSPFetchFailed",
            additionalInfo: error.message
        }
        // ocspResult MAY be omitted when status != Accepted

    RETURN response

{
  "certificateStatusRequests": [     // REQUIRED - Min: 1, Max: 4
    {
      "certificateHashData": {       // REQUIRED - CertificateHashDataType
        "hashAlgorithm": "SHA256 | SHA384 | SHA512",
        "issuerNameHash": "string (max 128)",
        "issuerKeyHash": "string (max 128)",
        "serialNumber": "string (max 40)"
      },

      "source": "CRL | OCSP",
        // REQUIRED - Whether to check via OCSP or CRL.

      "urls": ["string (max 2000)", ...]
        // REQUIRED - URL(s) of the OCSP responder or CRL distribution point.
        // Min: 1, Max: 5
    }
  ]
}

{
  "certificateStatus": [             // REQUIRED - Min: 1, Max: 4
    {
      "certificateHashData": {       // REQUIRED - echo back
        "hashAlgorithm": "SHA256 | SHA384 | SHA512",
        "issuerNameHash": "string (max 128)",
        "issuerKeyHash": "string (max 128)",
        "serialNumber": "string (max 40)"
      },

      "source": "CRL | OCSP",
        // REQUIRED - Source used for this status check.

      "status": "Good | Revoked | Unknown | Failed",
        // REQUIRED - Revocation status of the certificate.

      "nextUpdate": "date-time (ISO 8601)"
        // REQUIRED - When the status information will next be updated.
    }
  ]
}

HANDLE GetCertificateChainStatusRequest(request):
    results = []

    FOR EACH entry IN request.certificateStatusRequests:
        certHash = entry.certificateHashData
        source = entry.source
        urls = entry.urls

        // 1. Check local cache first
        cached = checkCache(certHash, source)
        IF cached IS NOT NULL AND cached.nextUpdate > now():
            results.add(cached)
            CONTINUE

        // 2. Not cached or expired - perform live check
        IF source == "OCSP":
            // req M07.FR.01: Perform OCSP request to one of the URLs
            result = performOCSPCheck(certHash, urls)

            IF result.success:
                // req M07.FR.03: Use the OCSP status (Good/Revoked/Unknown)
                results.add({
                    certificateHashData: certHash,
                    source: "OCSP",
                    status: result.ocspStatus,
                    nextUpdate: result.nextUpdate
                })
            ELSE:
                // req M07.FR.02: OCSP request failed
                results.add({
                    certificateHashData: certHash,
                    source: "OCSP",
                    status: "Failed",
                    nextUpdate: now() + 1hour
                })

        ELSE IF source == "CRL":
            // req M07.FR.04: Retrieve CRL from one of the URLs
            crl = downloadCRL(urls)

            IF crl IS NULL:
                // req M07.FR.05: CRL download failed
                results.add({
                    certificateHashData: certHash,
                    source: "CRL",
                    status: "Failed",
                    nextUpdate: now() + 1hour
                })
            ELSE:
                IF crl.contains(certHash.serialNumber):
                    // req M07.FR.06: Certificate is revoked
                    results.add({
                        certificateHashData: certHash,
                        source: "CRL",
                        status: "Revoked",
                        nextUpdate: crl.nextUpdate
                    })
                ELSE:
                    // req M07.FR.07: Certificate not in CRL -> Good
                    results.add({
                        certificateHashData: certHash,
                        source: "CRL",
                        status: "Good",
                        nextUpdate: crl.nextUpdate
                    })

        // Cache the result
        cacheResult(certHash, source, results.last())

    // req M07.FR.08: Respond with all results
    response.certificateStatus = results
    RETURN response

{
  "certificateStatus": [
    {
      "certificateHashData": {
        "hashAlgorithm": "SHA256",
        "issuerNameHash": "12345ABCDE",
        "issuerKeyHash": "ABCDE1234",
        "serialNumber": "AB123456789"
      },
      "source": "OCSP",
      "status": "Good",
      "nextUpdate": "2025-02-01T12:00Z"
    },
    {
      "certificateHashData": {
        "hashAlgorithm": "SHA256",
        "issuerNameHash": "ABCDE12345",
        "issuerKeyHash": "1234ABCDE",
        "serialNumber": "987634294239"
      },
      "source": "CRL",
      "status": "Good",
      "nextUpdate": "2025-02-01T12:00Z"
    }
  ]
}

{
  "reasonCode": "string (max 20)",
    // REQUIRED - Predefined code for the reason. Case-insensitive.

  "additionalInfo": "string (max 1024)"
    // OPTIONAL - Free-text additional information.
}

{
  "hashAlgorithm": "SHA256 | SHA384 | SHA512",
    // REQUIRED

  "issuerNameHash": "string (max 128)",
    // REQUIRED - Hash of the issuer's distinguished name (DN),
    // calculated over the DER encoding of the issuer's name field
    // in the certificate being checked.

  "issuerKeyHash": "string (max 128)",
    // REQUIRED - Hash of the DER encoded public key: the value
    // (excluding tag and length) of the subject public key field
    // in the issuer's certificate.

  "serialNumber": "string (max 40)"
    // REQUIRED - Hex string representation of the serial number
    // without '0x' prefix and without leading zeroes.
}

{
  "vendorId": "string (max 255)"
    // REQUIRED
}