ocpp-kit 0.5.0

Open Charge Point Protocol (OCPP 1.6J, 2.0.1, 2.1) toolkit for Rust: typed messages, OCPP-J framing, a sans-I/O protocol engine, and transports for charging stations, CSMS and local controllers.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
//! TLS for security profiles 2 and 3, on `rustls` (feature `rustls`).
//!
//! `rustls` negotiates TLS 1.2 and 1.3 only and offers no anonymous, null or export cipher
//! suites, which is exactly what A00.FR.313 / A00.FR.416 and A00.FR.320 / A00.FR.423
//! require. Nothing here can be configured back below that line.

use std::fmt;
use std::io;
use std::path::Path;
use std::sync::Arc;

use tokio_rustls::rustls;
use tokio_rustls::rustls::pki_types::pem::PemObject as _;
use tokio_rustls::rustls::pki_types::{CertificateDer, PrivateKeyDer, ServerName};

/// Why a TLS configuration could not be built.
#[derive(Debug)]
#[non_exhaustive]
pub enum TlsError {
    /// A PEM file could not be read.
    Io(io::Error),
    /// `rustls` rejected the configuration.
    Rustls(rustls::Error),
    /// A PEM file held nothing usable.
    Pem(String),
}

impl fmt::Display for TlsError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TlsError::Io(error) => write!(f, "reading a PEM file: {error}"),
            TlsError::Rustls(error) => write!(f, "rustls: {error}"),
            TlsError::Pem(what) => write!(f, "{what}"),
        }
    }
}

impl std::error::Error for TlsError {}

impl From<io::Error> for TlsError {
    fn from(error: io::Error) -> Self {
        TlsError::Io(error)
    }
}

impl From<rustls::Error> for TlsError {
    fn from(error: rustls::Error) -> Self {
        TlsError::Rustls(error)
    }
}

fn provider() -> Arc<rustls::crypto::CryptoProvider> {
    // Chosen explicitly rather than through the process-wide default, so a host application
    // that installs a different provider cannot silently change our cipher suites.
    Arc::new(rustls::crypto::ring::default_provider())
}

fn read_certs(path: &Path) -> Result<Vec<CertificateDer<'static>>, TlsError> {
    let certs: Vec<_> = CertificateDer::pem_file_iter(path)
        .map_err(|error| TlsError::Pem(format!("{}: {error}", path.display())))?
        .collect::<Result<_, _>>()
        .map_err(|error| TlsError::Pem(format!("{}: {error}", path.display())))?;
    if certs.is_empty() {
        return Err(TlsError::Pem(format!(
            "{} contains no certificates",
            path.display()
        )));
    }
    Ok(certs)
}

fn read_key(path: &Path) -> Result<PrivateKeyDer<'static>, TlsError> {
    PrivateKeyDer::from_pem_file(path)
        .map_err(|error| TlsError::Pem(format!("{}: {error}", path.display())))
}

/// The client side of TLS, for a Charging Station using security profile 2 or 3.
///
/// ```no_run
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// use ocpp_kit::transport::ClientTls;
///
/// // Profile 2: trust one private CSMS root.
/// let profile2 = ClientTls::builder().root_file("csms-root.pem")?.build()?;
///
/// // Profile 3: additionally present the station's own certificate.
/// let profile3 = ClientTls::builder()
///     .root_file("csms-root.pem")?
///     .client_certificate("station-chain.pem", "station-key.pem")?
///     .build()?;
/// # let _ = (profile2, profile3);
/// # Ok(()) }
/// ```
#[derive(Clone)]
pub struct ClientTls {
    config: Arc<rustls::ClientConfig>,
}

impl ClientTls {
    /// Starts an empty configuration.
    #[must_use]
    pub fn builder() -> ClientTlsBuilder {
        ClientTlsBuilder {
            roots: rustls::RootCertStore::empty(),
            identity: None,
            allow_wildcards: false,
        }
    }

    /// Trusts the Mozilla root programme, which is what a publicly issued CSMS certificate
    /// chains to.
    pub fn with_webpki_roots() -> Result<Self, TlsError> {
        ClientTls::builder().webpki_roots().build()
    }

    /// Trusts exactly the certificates in `path` — the usual choice, since a CSMS root is
    /// normally private (`InstallCertificate` with `CSMSRootCertificate`).
    pub fn with_root_file(path: impl AsRef<Path>) -> Result<Self, TlsError> {
        ClientTls::builder().root_file(path)?.build()
    }

    /// Wraps an existing `rustls` configuration.
    #[must_use]
    pub fn from_config(config: Arc<rustls::ClientConfig>) -> Self {
        Self { config }
    }

    pub(crate) fn connector(&self) -> tokio_rustls::TlsConnector {
        tokio_rustls::TlsConnector::from(self.config.clone())
    }

    pub(crate) fn server_name(host: &str) -> Result<ServerName<'static>, TlsError> {
        ServerName::try_from(host.to_owned())
            .map_err(|_| TlsError::Pem(format!("{host} is not a valid TLS server name")))
    }
}

impl fmt::Debug for ClientTls {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("ClientTls")
    }
}

/// The standard verifier, plus the refusal of a wildcard name ([`ClientTlsBuilder::
/// allow_wildcard_server_certificates`]).
///
/// The chain, validity and host name are checked by the inner verifier first; only a
/// certificate that already passes is then refused for carrying a wildcard. rustls matches the
/// subjectAltName and ignores the commonName, so the SAN is where a wildcard takes effect.
#[derive(Debug)]
struct NoWildcards {
    inner: Arc<rustls::client::WebPkiServerVerifier>,
}

impl rustls::client::danger::ServerCertVerifier for NoWildcards {
    fn verify_server_cert(
        &self,
        end_entity: &CertificateDer<'_>,
        intermediates: &[CertificateDer<'_>],
        server_name: &ServerName<'_>,
        ocsp_response: &[u8],
        now: rustls::pki_types::UnixTime,
    ) -> Result<rustls::client::danger::ServerCertVerified, rustls::Error> {
        let verified = self.inner.verify_server_cert(
            end_entity,
            intermediates,
            server_name,
            ocsp_response,
            now,
        )?;
        let certificate = webpki::EndEntityCert::try_from(end_entity).map_err(|_| {
            rustls::Error::InvalidCertificate(rustls::CertificateError::BadEncoding)
        })?;
        if certificate
            .valid_dns_names()
            .any(|name| name.starts_with("*."))
        {
            return Err(rustls::Error::InvalidCertificate(
                rustls::CertificateError::ApplicationVerificationFailure,
            ));
        }
        Ok(verified)
    }

    fn verify_tls12_signature(
        &self,
        message: &[u8],
        cert: &CertificateDer<'_>,
        dss: &rustls::DigitallySignedStruct,
    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
        self.inner.verify_tls12_signature(message, cert, dss)
    }

    fn verify_tls13_signature(
        &self,
        message: &[u8],
        cert: &CertificateDer<'_>,
        dss: &rustls::DigitallySignedStruct,
    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
        self.inner.verify_tls13_signature(message, cert, dss)
    }

    fn supported_verify_schemes(&self) -> Vec<rustls::SignatureScheme> {
        self.inner.supported_verify_schemes()
    }
}

/// Collects the trust anchors and, for profile 3, the client identity.
pub struct ClientTlsBuilder {
    roots: rustls::RootCertStore,
    identity: Option<(Vec<CertificateDer<'static>>, PrivateKeyDer<'static>)>,
    allow_wildcards: bool,
}

impl ClientTlsBuilder {
    /// Adds the Mozilla root programme.
    #[must_use]
    pub fn webpki_roots(mut self) -> Self {
        self.roots
            .roots
            .extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());
        self
    }

    /// Adds every certificate in a PEM file as a trust anchor.
    pub fn root_file(mut self, path: impl AsRef<Path>) -> Result<Self, TlsError> {
        for cert in read_certs(path.as_ref())? {
            self.roots.add(cert)?;
        }
        Ok(self)
    }

    /// Adds a trust anchor from DER.
    pub fn root_der(mut self, der: CertificateDer<'static>) -> Result<Self, TlsError> {
        self.roots.add(der)?;
        Ok(self)
    }

    /// Presents this certificate chain and key to the CSMS — security profile 3.
    pub fn client_certificate(
        mut self,
        chain: impl AsRef<Path>,
        key: impl AsRef<Path>,
    ) -> Result<Self, TlsError> {
        self.identity = Some((read_certs(chain.as_ref())?, read_key(key.as_ref())?));
        Ok(self)
    }

    /// Accepts a CSMS certificate whose name is a wildcard (`*.example.com`).
    ///
    /// Refused by default, on every version: "OCPP-compliant behavior is that a Charging
    /// Station rejects a connection from a CSMS that presents a wildcard certificate. It is
    /// highly RECOMMENDED to not allow wildcard certificates" (2.x
    /// `SecurityCtrlr.AllowCSMSTLSWildcards`; 1.6 Security Whitepaper edition 4 §7.7,
    /// `AllowCentralSystemTLSWildcards`). Call this when that variable is `true`.
    #[must_use]
    pub fn allow_wildcard_server_certificates(mut self) -> Self {
        self.allow_wildcards = true;
        self
    }

    /// Builds the configuration.
    pub fn build(self) -> Result<ClientTls, TlsError> {
        if self.roots.is_empty() {
            return Err(TlsError::Pem(
                "no trust anchors: call `webpki_roots()` or `root_file()`".to_owned(),
            ));
        }
        let provider = provider();
        let webpki = rustls::client::WebPkiServerVerifier::builder_with_provider(
            Arc::new(self.roots),
            provider.clone(),
        )
        .build()
        .map_err(|error| TlsError::Pem(error.to_string()))?;
        let verifier: Arc<dyn rustls::client::danger::ServerCertVerifier> = if self.allow_wildcards
        {
            webpki
        } else {
            Arc::new(NoWildcards { inner: webpki })
        };
        let builder = rustls::ClientConfig::builder_with_provider(provider)
            .with_safe_default_protocol_versions()?
            .dangerous()
            .with_custom_certificate_verifier(verifier);
        let config = match self.identity {
            Some((chain, key)) => builder.with_client_auth_cert(chain, key)?,
            None => builder.with_no_client_auth(),
        };
        Ok(ClientTls {
            config: Arc::new(config),
        })
    }
}

/// The server side of TLS, for a CSMS or a Local Controller.
#[derive(Clone)]
pub struct ServerTls {
    config: Arc<rustls::ServerConfig>,
    /// Whether a client certificate is demanded — security profile 3.
    mutual: bool,
}

impl ServerTls {
    /// Serves `chain` / `key` without asking for a client certificate (profile 2).
    pub fn new(chain: impl AsRef<Path>, key: impl AsRef<Path>) -> Result<Self, TlsError> {
        let certs = read_certs(chain.as_ref())?;
        let key = read_key(key.as_ref())?;
        let config = rustls::ServerConfig::builder_with_provider(provider())
            .with_safe_default_protocol_versions()?
            .with_no_client_auth()
            .with_single_cert(certs, key)?;
        Ok(Self {
            config: Arc::new(config),
            mutual: false,
        })
    }

    /// Demands a client certificate issued under `client_roots` — security profile 3.
    ///
    /// The verified end-entity certificate reaches the authenticator as
    /// [`Credentials::ClientCertificate`](super::Credentials::ClientCertificate), so a CSMS
    /// can still bind it to the identity in the URL.
    pub fn with_client_auth(
        chain: impl AsRef<Path>,
        key: impl AsRef<Path>,
        client_roots: impl AsRef<Path>,
    ) -> Result<Self, TlsError> {
        let certs = read_certs(chain.as_ref())?;
        let key = read_key(key.as_ref())?;
        let mut roots = rustls::RootCertStore::empty();
        for cert in read_certs(client_roots.as_ref())? {
            roots.add(cert)?;
        }
        let verifier = rustls::server::WebPkiClientVerifier::builder_with_provider(
            Arc::new(roots),
            provider(),
        )
        .build()
        .map_err(|error| TlsError::Pem(error.to_string()))?;
        let config = rustls::ServerConfig::builder_with_provider(provider())
            .with_safe_default_protocol_versions()?
            .with_client_cert_verifier(verifier)
            .with_single_cert(certs, key)?;
        Ok(Self {
            config: Arc::new(config),
            mutual: true,
        })
    }

    /// Wraps an existing `rustls` configuration.
    #[must_use]
    pub fn from_config(config: Arc<rustls::ServerConfig>, mutual: bool) -> Self {
        Self { config, mutual }
    }

    /// Whether this configuration implements security profile 3.
    #[must_use]
    pub fn is_mutual(&self) -> bool {
        self.mutual
    }

    pub(crate) fn acceptor(&self) -> tokio_rustls::TlsAcceptor {
        tokio_rustls::TlsAcceptor::from(self.config.clone())
    }
}

impl fmt::Debug for ServerTls {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ServerTls")
            .field("mutual", &self.mutual)
            .finish_non_exhaustive()
    }
}

#[cfg(test)]
mod wildcard_tests {
    use super::*;
    use rustls::client::danger::ServerCertVerifier as _;

    // `testdata/`: a P-256 CA and two leaves it signed — `csms.example.com` and
    // `*.example.com` — valid for 100 years from 2026-11-07, made with `openssl req -x509` /
    // `openssl x509 -req`. Committed rather than generated per run so the tests need no
    // certificate-generating dependency.
    const CA: &[u8] = include_bytes!("testdata/ca.pem");
    const PLAIN: &[u8] = include_bytes!("testdata/plain.pem");
    const WILD: &[u8] = include_bytes!("testdata/wild.pem");

    fn der(pem: &[u8]) -> CertificateDer<'static> {
        CertificateDer::from_pem_slice(pem).unwrap()
    }

    fn verifier(allow_wildcards: bool) -> Arc<rustls::ClientConfig> {
        let mut builder = ClientTls::builder().root_der(der(CA)).unwrap();
        if allow_wildcards {
            builder = builder.allow_wildcard_server_certificates();
        }
        builder.build().unwrap().config
    }

    /// 2.x `AllowCSMSTLSWildcards`, 1.6 `AllowCentralSystemTLSWildcards`: a wildcard CSMS
    /// certificate is refused unless allowed; a plain one is accepted either way.
    #[test]
    fn a_wildcard_csms_certificate_is_refused_unless_allowed() {
        let name = ServerName::try_from("csms.example.com").unwrap();
        let now = rustls::pki_types::UnixTime::now();
        let check = |leaf: &[u8], name: &ServerName<'_>, allow: bool| {
            let leaf = der(leaf);
            let mut roots = rustls::RootCertStore::empty();
            roots.add(der(CA)).unwrap();
            let inner = rustls::client::WebPkiServerVerifier::builder_with_provider(
                Arc::new(roots),
                provider(),
            )
            .build()
            .unwrap();
            if allow {
                inner
                    .verify_server_cert(&leaf, &[], name, &[], now)
                    .map(|_| ())
            } else {
                NoWildcards { inner }
                    .verify_server_cert(&leaf, &[], name, &[], now)
                    .map(|_| ())
            }
        };
        let other = ServerName::try_from("other.example.org").unwrap();
        assert!(check(PLAIN, &name, false).is_ok());
        assert_eq!(
            check(WILD, &name, false).unwrap_err(),
            rustls::Error::InvalidCertificate(
                rustls::CertificateError::ApplicationVerificationFailure
            )
        );
        assert!(check(WILD, &name, true).is_ok());
        // A certificate that fails the ordinary checks still fails them first.
        assert!(matches!(
            check(PLAIN, &other, false).unwrap_err(),
            rustls::Error::InvalidCertificate(
                rustls::CertificateError::NotValidForName
                    | rustls::CertificateError::NotValidForNameContext { .. }
            )
        ));
    }

    /// The builder wires the refusing verifier in by default.
    #[test]
    fn the_builder_refuses_wildcards_by_default() {
        let strict = verifier(false);
        let lax = verifier(true);
        assert!(format!("{strict:?}").contains("NoWildcards"));
        assert!(!format!("{lax:?}").contains("NoWildcards"));
    }
}