pptx 0.1.0

A Rust library for creating and manipulating PowerPoint (.pptx) files
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

//! Core types for digital signatures: enums and structs.

/// The hash algorithm used for digest computation.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HashAlgorithm {
    /// **Warning**: SHA-1 is cryptographically broken. Use SHA-256 or stronger for new signatures.
    Sha1,
    Sha256,
    Sha512,
}

impl HashAlgorithm {
    /// Return the W3C XML Signature algorithm URI for this hash algorithm.
    #[must_use]
    pub const fn algorithm_uri(&self) -> &'static str {
        match self {
            Self::Sha1 => "http://www.w3.org/2000/09/xmldsig#sha1",
            Self::Sha256 => "http://www.w3.org/2001/04/xmlenc#sha256",
            Self::Sha512 => "http://www.w3.org/2001/04/xmlenc#sha512",
        }
    }

    /// Return the algorithm name as used in XML attributes.
    #[must_use]
    pub const fn name(&self) -> &'static str {
        match self {
            Self::Sha1 => "SHA1",
            Self::Sha256 => "SHA256",
            Self::Sha512 => "SHA512",
        }
    }
}

/// The commitment type for the signature.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SignatureCommitment {
    Created,
    Approved,
    Reviewed,
}

impl SignatureCommitment {
    /// Return the OPC signature commitment type URI.
    #[must_use]
    pub const fn commitment_uri(&self) -> &'static str {
        match self {
            Self::Created => {
                "http://schemas.openxmlformats.org/package/2006/RelationshipTransform/opc-SignatureOrigin/created"
            }
            Self::Approved => {
                "http://schemas.openxmlformats.org/package/2006/RelationshipTransform/opc-SignatureOrigin/approved"
            }
            Self::Reviewed => {
                "http://schemas.openxmlformats.org/package/2006/RelationshipTransform/opc-SignatureOrigin/reviewed"
            }
        }
    }
}

/// Information about the person who created the signature.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SignerInfo {
    /// The signer's display name.
    pub name: String,
    /// The signer's email address.
    pub email: Option<String>,
    /// The signer's title or role.
    pub title: Option<String>,
}

impl SignerInfo {
    /// Create a new `SignerInfo` with only a name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            email: None,
            title: None,
        }
    }

    /// Builder method: set the email address.
    #[must_use]
    pub fn with_email(mut self, email: impl Into<String>) -> Self {
        self.email = Some(email.into());
        self
    }

    /// Builder method: set the title.
    #[must_use]
    pub fn with_title(mut self, title: impl Into<String>) -> Self {
        self.title = Some(title.into());
        self
    }
}

/// Represents the metadata structure for a digital signature part.
///
/// Generates a W3C XML Signature skeleton within the `_xmlsignatures/` directory of the OPC
/// package. **Does not perform cryptographic signing** — `DigestValue` and `SignatureValue` are
/// empty placeholders. To produce a valid signature, use an external signing tool or ceremony
/// after generating the PPTX.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DigitalSignature {
    /// Information about the signer.
    pub signer: SignerInfo,
    /// The hash algorithm for digest computation.
    pub hash_algorithm: HashAlgorithm,
    /// Optional ISO 8601 datetime string for when the signature was created.
    pub sign_time: Option<String>,
    /// The commitment type for the signature.
    pub commitment: SignatureCommitment,
}

impl DigitalSignature {
    /// Create a new digital signature with the given signer and algorithm.
    #[must_use]
    pub const fn new(signer: SignerInfo, algorithm: HashAlgorithm) -> Self {
        Self {
            signer,
            hash_algorithm: algorithm,
            sign_time: None,
            commitment: SignatureCommitment::Created,
        }
    }

    /// Builder method: set the commitment type.
    #[must_use]
    pub const fn with_commitment(mut self, commitment: SignatureCommitment) -> Self {
        self.commitment = commitment;
        self
    }

    /// Builder method: set the signing time.
    #[must_use]
    pub fn with_sign_time(mut self, time: impl Into<String>) -> Self {
        self.sign_time = Some(time.into());
        self
    }
}