ssign-core 0.1.8

The Certum SimplySign cloud-signing pipeline behind ssign: OAuth login, card/cert fetch, remote signature, and local Authenticode/PKCS#7 assembly — the reusable half shared by the ssign CLI and the ssign-pkcs11 module.
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
//! A live cloud signing session — the [`auth`] → [`card`] → [`sign`] steps
//! bundled behind one object.
//!
//! Both the CLI and the `ssign-pkcs11` module log in once and then sign many
//! digests through this handle. It also precomputes the pieces a PKCS#11 module
//! needs to describe the key to osslsigncode/signtool: the certificate (DER),
//! its public key (PKCS#1 RSAPublicKey DER), and a stable id linking the two.
//!
//! # Session cache
//!
//! A PKCS#11 caller like osslsigncode reloads the module — and thus logs in
//! again — for every file it signs. Certum rejects a reused TOTP code, so
//! signing several files in a row would fail after the first. To avoid that,
//! [`CloudSession::save`] persists the OAuth token (valid ~30 min) and
//! [`CloudSession::load_cached`] reuses it, so only the first sign needs an OTP.

use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Mutex;
use std::time::{SystemTime, UNIX_EPOCH};

use crate::{auth, card, client, sign};
use anyhow::{Context, Result};
use reqwest::blocking::Client;
use sha1::{Digest, Sha1};
use x509_cert::der::Decode;
use x509_cert::Certificate;
use zeroize::Zeroizing;

/// How long a cached token is trusted before we log in again. The real token
/// lives ~30 min; we stay well inside that so a sign never starts on a token
/// about to expire.
const CACHE_TTL_SECS: u64 = 20 * 60;

/// An authenticated Certum cloud session ready to sign SHA-256 digests.
pub struct CloudSession {
    http: Client,
    token: Zeroizing<String>,
    card: card::Card,
    cert_der: Vec<u8>,
    pubkey_der: Vec<u8>,
    key_id: Vec<u8>,
    /// Memoized last `(digest, signature)`. PKCS#11 clients call `C_Sign` twice
    /// per signature — once with a null buffer to learn the length, once to get
    /// the bytes — which would otherwise be two cloud round-trips for the same
    /// digest. RSA PKCS#1 v1.5 is deterministic, so caching by digest is always
    /// correct.
    last: Mutex<Option<([u8; 32], Vec<u8>)>>,
}

impl CloudSession {
    /// Log in (email + current 6-digit code) and materialize the card,
    /// certificate and the derived key descriptors.
    pub fn open(email: &str, otp_code: &str) -> Result<Self> {
        let token = Zeroizing::new(auth::login(email, otp_code)?.0);
        let http = client::client()?;
        let card = card::fetch(&http, &token)?;
        Self::from_parts(http, token, card)
    }

    /// Build a session from an already-issued token and card (no login).
    fn from_parts(http: Client, token: Zeroizing<String>, card: card::Card) -> Result<Self> {
        let cert_der = crate::authenticode::pem_to_der(&card.certificate_pem)
            .context("decoding the signing certificate")?;
        let cert = Certificate::from_der(&cert_der).context("parsing the signing certificate")?;
        // The PKCS#1 `RSAPublicKey` (modulus + exponent) — the bare content of
        // the SPKI's BIT STRING, which is the shape PKCS#11 clients expect from
        // a public-key object's CKA_VALUE.
        let pubkey_der = cert
            .tbs_certificate()
            .subject_public_key_info()
            .subject_public_key
            .raw_bytes()
            .to_vec();
        // Conventional CKA_ID: a stable hash tying the certificate to its key so
        // a PKCS#11 client that finds the cert can find the matching key.
        let key_id = Sha1::digest(&cert_der).to_vec();

        Ok(Self {
            http,
            token,
            card,
            cert_der,
            pubkey_der,
            key_id,
            last: Mutex::new(None),
        })
    }

    /// The signing certificate (DER).
    pub fn certificate_der(&self) -> &[u8] {
        &self.cert_der
    }

    /// The certificate's public key as a PKCS#1 `RSAPublicKey` DER
    /// (modulus + exponent) — the shape PKCS#11 clients parse.
    pub fn public_key_der(&self) -> &[u8] {
        &self.pubkey_der
    }

    /// A stable id linking the certificate and its private key (CKA_ID).
    pub fn key_id(&self) -> &[u8] {
        &self.key_id
    }

    /// The card serial this session signs with (`cardno`).
    pub fn card_serial(&self) -> &str {
        &self.card.serial
    }

    /// Ask the cloud HSM to sign one SHA-256 digest; returns the raw RSA
    /// PKCS#1 v1.5 signature. The result is memoized per digest so the twin
    /// `C_Sign` calls a PKCS#11 client makes cost a single cloud round-trip.
    pub fn sign_sha256(&self, digest: &[u8; 32]) -> Result<Vec<u8>> {
        if let Some((cached_digest, signature)) = self.last.lock().unwrap().as_ref() {
            if cached_digest == digest {
                return Ok(signature.clone());
            }
        }
        let signature = sign::request(&self.http, &self.token, &self.card, digest)?;
        *self.last.lock().unwrap() = Some((*digest, signature.clone()));
        Ok(signature)
    }

    // --- session cache -----------------------------------------------------

    /// Reuse a previously saved session for `email`, if the cached token is
    /// still valid. Best-effort: any problem (missing file, wrong account,
    /// expired token, parse error) yields `None` so the caller logs in afresh.
    pub fn load_cached(email: &str) -> Option<Self> {
        Self::load_cached_from(&cache_path()?, email)
    }

    /// [`load_cached`](Self::load_cached) against an explicit path.
    fn load_cached_from(path: &Path, email: &str) -> Option<Self> {
        // A cache that is not ours, or that others can read, was not written
        // by write_private: ignore it rather than sign with whatever it holds.
        #[cfg(unix)]
        {
            use std::os::unix::fs::{MetadataExt, PermissionsExt};
            let meta = fs::symlink_metadata(path).ok()?;
            if !meta.is_file()
                || meta.uid() != current_uid()
                || meta.permissions().mode() & 0o077 != 0
            {
                return None;
            }
        }
        let raw = Zeroizing::new(fs::read(path).ok()?);
        let v: serde_json::Value = serde_json::from_slice(&raw).ok()?;
        if v.get("email")?.as_str()? != email {
            return None;
        }
        let expires_at = v.get("expires_at")?.as_u64()?;
        if now() + 120 >= expires_at {
            return None;
        }
        let token = Zeroizing::new(v.get("token")?.as_str()?.to_string());
        let serial = v.get("serial")?.as_str()?.to_string();
        let certificate_pem = v.get("cert_pem")?.as_str()?.as_bytes().to_vec();
        let card = card::Card {
            serial,
            certificate_pem,
        };
        Self::from_parts(client::client().ok()?, token, card).ok()
    }

    /// Persist this session's token + card so the next process can reuse it
    /// without an OTP. Best-effort; a failure to write is not fatal.
    pub fn save(&self, email: &str) {
        let Some(path) = cache_path() else { return };
        self.save_to(&path, email);
    }

    /// [`save`](Self::save) against an explicit path.
    fn save_to(&self, path: &Path, email: &str) {
        let doc = serde_json::json!({
            "v": 1,
            "email": email,
            "token": self.token.as_str(),
            "expires_at": now() + CACHE_TTL_SECS,
            "serial": self.card.serial,
            "cert_pem": String::from_utf8_lossy(&self.card.certificate_pem),
        });
        let _ = write_private(path, Zeroizing::new(doc.to_string()).as_bytes());
    }
}

fn now() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0)
}

/// `$XDG_RUNTIME_DIR/ssign/session.json`, falling back to `$HOME/.cache`. The
/// token here can sign for ~30 min, so the file is written user-private (see
/// [`write_private`]).
///
/// On Windows the system temp dir is a last resort: it is per-user and
/// ACL-protected (`%LOCALAPPDATA%\Temp`). A Unix temp dir is shared by every
/// account on the machine, which makes it no place for a token that signs
/// code: without a private directory there is simply no cache, and the next
/// signature asks for an OTP.
fn cache_path() -> Option<PathBuf> {
    let base = std::env::var_os("XDG_RUNTIME_DIR")
        .map(PathBuf::from)
        .or_else(|| std::env::var_os("HOME").map(|h| PathBuf::from(h).join(".cache")));
    #[cfg(windows)]
    let base = base.or_else(|| Some(std::env::temp_dir()));
    Some(base?.join("ssign").join("session.json"))
}

/// Write `data` to `path` with owner-only permissions, creating the parent
/// directory (also owner-only on Unix).
///
/// The token goes into a temporary file created owner-only from the start, and
/// is then renamed over `path`. Writing first and restricting afterwards would
/// leave it readable under the default umask for a moment, and a symlink
/// planted at `path` would be followed; `rename` replaces the link instead.
///
/// On Unix the directory must be ours and closed to everyone else. One that
/// already exists and belongs to another account (a shared parent, a
/// pre-created `ssign/`) could hand the token to that account, so nothing is
/// written there at all.
fn write_private(path: &Path, data: &[u8]) -> std::io::Result<()> {
    use std::io::Write;

    let dir = path
        .parent()
        .ok_or_else(|| std::io::Error::other("cache path has no parent directory"))?;
    fs::create_dir_all(dir)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::{MetadataExt, PermissionsExt};
        let meta = fs::symlink_metadata(dir)?;
        if !meta.is_dir() || meta.uid() != current_uid() {
            return Err(std::io::Error::other(
                "cache directory does not belong to this user",
            ));
        }
        fs::set_permissions(dir, fs::Permissions::from_mode(0o700))?;
    }

    let tmp = dir.join(format!(".session.{}.tmp", std::process::id()));
    let _ = fs::remove_file(&tmp);
    let mut options = fs::OpenOptions::new();
    options.write(true).create_new(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.mode(0o600);
    }
    let written = (|| {
        let mut file = options.open(&tmp)?;
        file.write_all(data)?;
        file.sync_all()?;
        fs::rename(&tmp, path)
    })();
    if written.is_err() {
        let _ = fs::remove_file(&tmp);
    }
    written
}

/// The effective user id, to tell our own files from anyone else's.
#[cfg(unix)]
fn current_uid() -> u32 {
    // SAFETY: geteuid has no preconditions and cannot fail.
    unsafe { libc::geteuid() }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A session built straight from parts, with no network involved.
    fn fake_session() -> CloudSession {
        use x509_cert::der::pem::LineEnding;
        use x509_cert::der::EncodePem;
        let cert_der = include_bytes!("../tests/fixtures/selftest_cert.der");
        let pem = Certificate::from_der(cert_der)
            .expect("parse test certificate")
            .to_pem(LineEnding::LF)
            .expect("encode test certificate");
        let card = card::Card {
            serial: "1234567890".into(),
            certificate_pem: pem.into_bytes(),
        };
        CloudSession::from_parts(
            client::client().unwrap(),
            Zeroizing::new("token-abc".into()),
            card,
        )
        .expect("build session from parts")
    }

    fn temp_cache(name: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!("ssign-cache-test-{name}"));
        let _ = fs::remove_dir_all(&dir);
        dir.join("session.json")
    }

    #[test]
    fn a_saved_session_is_reloaded_without_a_new_login() {
        // The bug this guards: the CLI used to call `auth::login` directly and
        // never write the cache, so `ssign-pkcs11` logged in a second time and
        // replayed a Certum code that is only accepted once.
        let path = temp_cache("roundtrip");
        fake_session().save_to(&path, "user@example.com");

        let loaded = CloudSession::load_cached_from(&path, "user@example.com")
            .expect("cached session should reload");
        assert_eq!(loaded.token.as_str(), "token-abc");
        assert_eq!(loaded.card_serial(), "1234567890");
        assert_eq!(loaded.certificate_der(), fake_session().certificate_der());
        assert_eq!(loaded.key_id(), fake_session().key_id());
    }

    #[test]
    fn the_cache_is_owner_only() {
        let path = temp_cache("perms");
        fake_session().save_to(&path, "user@example.com");
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = fs::metadata(&path).unwrap().permissions().mode();
            assert_eq!(mode & 0o777, 0o600, "token file must not be world-readable");
        }
    }

    #[cfg(unix)]
    #[test]
    fn a_symlink_at_the_cache_path_is_replaced_not_followed() {
        let path = temp_cache("symlink");
        fs::create_dir_all(path.parent().unwrap()).unwrap();
        let victim = path.parent().unwrap().join("victim");
        fs::write(&victim, "untouched").unwrap();
        std::os::unix::fs::symlink(&victim, &path).unwrap();

        fake_session().save_to(&path, "user@example.com");

        assert_eq!(fs::read_to_string(&victim).unwrap(), "untouched");
        let meta = fs::symlink_metadata(&path).unwrap();
        assert!(
            meta.file_type().is_file(),
            "the link itself must have been replaced"
        );
    }

    #[cfg(unix)]
    #[test]
    fn a_cache_readable_by_others_is_ignored() {
        use std::os::unix::fs::PermissionsExt;
        let path = temp_cache("readable");
        fake_session().save_to(&path, "user@example.com");
        fs::set_permissions(&path, fs::Permissions::from_mode(0o644)).unwrap();
        assert!(CloudSession::load_cached_from(&path, "user@example.com").is_none());
    }

    #[test]
    fn a_cache_for_another_account_is_ignored() {
        let path = temp_cache("otheraccount");
        fake_session().save_to(&path, "user@example.com");
        assert!(CloudSession::load_cached_from(&path, "someone-else@example.com").is_none());
    }

    #[test]
    fn an_expired_cache_is_ignored() {
        let path = temp_cache("expired");
        fake_session().save_to(&path, "user@example.com");
        // Rewrite the expiry into the past, leaving everything else intact.
        let mut v: serde_json::Value = serde_json::from_slice(&fs::read(&path).unwrap()).unwrap();
        v["expires_at"] = serde_json::json!(now() - 1);
        fs::write(&path, v.to_string()).unwrap();
        assert!(CloudSession::load_cached_from(&path, "user@example.com").is_none());
    }

    #[test]
    fn a_cache_about_to_expire_is_ignored() {
        // A token with a minute left would expire mid-batch: refuse it rather
        // than start signing on it.
        let path = temp_cache("nearlyexpired");
        fake_session().save_to(&path, "user@example.com");
        let mut v: serde_json::Value = serde_json::from_slice(&fs::read(&path).unwrap()).unwrap();
        v["expires_at"] = serde_json::json!(now() + 60);
        fs::write(&path, v.to_string()).unwrap();
        assert!(CloudSession::load_cached_from(&path, "user@example.com").is_none());
    }

    #[test]
    fn a_missing_or_corrupt_cache_is_not_fatal() {
        let path = temp_cache("corrupt");
        assert!(CloudSession::load_cached_from(&path, "user@example.com").is_none());
        fs::create_dir_all(path.parent().unwrap()).unwrap();
        fs::write(&path, b"not json at all").unwrap();
        assert!(CloudSession::load_cached_from(&path, "user@example.com").is_none());
    }

    /// The PKCS#11 key material is what osslsigncode/signtool match a cert to
    /// its key by, so a dependency bump must not move it. Pinned from the test
    /// certificate; verified byte for byte across x509-cert 0.2 -> 0.3 and
    /// der 0.7 -> 0.8, which turned the certificate fields into accessors.
    #[test]
    fn key_material_is_stable() {
        let s = fake_session();
        assert_eq!(hex::encode(s.public_key_der()), "3082020a0282020100b52b48b82dfdc0fc91f3b914bbd4defad5b198f837c2b43a917a70f37fd3542bfe54a3c32fd1fb15de905300f054850a74b57b8ea30664ec23cbd7aa25dc2d51e47b4a6a934e837acd3ded5197afab9b0be48ad29277d28ec95a35c37c71e603bdd8c0143d2d00148f4ce590d25d1f9d8383cec11b15bd2f117b3fefc4f5c13a1f2b046cc34906d221f9a78a631a5db9448f62c1235a4cc5ed0033e86507cc68cc53e7781e60eedae4b4ba6e95520a7ec944fa4743baf919f2772c55a96c0042a31f60c9b4b4276e87b8666bc71c6288af0e8c0c65573211d827be7088f0d81c3227897b37448fb0d3da50712a74c6f04cd71aeed80e43202fc28508745fecd4bca09d6070068a1c0b73816aa71af5310c77a6cb70d2b430c3a3412f52bf7d620fe63ec871eee12b562c8b22b43fc7ce20e60ed822a2494462d9f8b7c0c8800cd414032256c4792b7a8abfc1d2e82e607752e55ca61075d0aadca88147714532231c8ff0f9a41d10083ce915bc2984d2a960ea3182b1a5f6a71378c6d75fdde7384f76dbea7f988b2b0720fcf341841fa59cf4c0d812bd48b452c37ac8e875c1a1a954f3be35d95c743a356ffbd5bab31cbe04681d489db763bf59034c40b500d9ae34824f65b57eec2f72ef56474f2930167cea1a6d0baff58dee2d5f199fb05b6b44edb2dcab0cc847d15d74ee6bd211c37ba1894a989ef2c0b5d99980e1cf0203010001");
        assert_eq!(
            hex::encode(s.key_id()),
            "533cb9753a556dcb175b0698e83084f6888d5ad3"
        );
    }
}