Struct apple_codesign::embedded_signature_builder::EmbeddedSignatureBuilder

pub struct EmbeddedSignatureBuilder<'a> { /* private fields */ }

An entity for producing and writing EmbeddedSignature.

This entity can be used to incrementally build up super blob data.

Implementations

impl<'a> EmbeddedSignatureBuilder<'a>

pub fn new_for_stapling(
    signature: EmbeddedSignature<'a>
) -> Result<Self, AppleCodesignError>

Create a new instance suitable for stapling a notarization ticket.

This starts with an existing EmbeddedSignature / superblob because stapling a notarization ticket just adds a new ticket slot without modifying existing slots.

Examples found in repository

src/dmg.rs (line 295)

    pub fn staple_file(
        &self,
        fh: &mut File,
        ticket_data: Vec<u8>,
    ) -> Result<(), AppleCodesignError> {
        warn!(
            "stapling DMG with {} byte notarization ticket",
            ticket_data.len()
        );

        let reader = DmgReader::new(fh)?;
        let koly = reader.koly().clone();
        let signature = reader
            .embedded_signature()?
            .ok_or(AppleCodesignError::DmgStapleNoSignature)?;

        let mut builder = EmbeddedSignatureBuilder::new_for_stapling(signature)?;
        builder.add_notarization_ticket(ticket_data)?;

        let signature = builder.create_superblob()?;

        Self::write_embedded_signature(fh, koly, &signature)
    }

pub fn code_directory(&self) -> Option<&CodeDirectoryBlob<'_>>

Obtain the code directory registered with this instance.

Examples found in repository

src/embedded_signature_builder.rs (line 173)

    pub fn add_code_directory(
        &mut self,
        cd_slot: CodeSigningSlot,
        mut cd: CodeDirectoryBlob<'a>,
    ) -> Result<&CodeDirectoryBlob, AppleCodesignError> {
        if matches!(self.state, BlobsState::SignatureAdded) {
            return Err(AppleCodesignError::SignatureBuilder(
                "cannot add code directory after signature data added",
            ));
        }

        for (slot, blob) in &self.blobs {
            // Not all slots are expressible in the cd specials list!
            if !slot.is_code_directory_specials_expressible() {
                continue;
            }

            let digest = blob.digest_with(cd.digest_type)?;

            cd.set_slot_digest(*slot, digest)?;
        }

        self.blobs.insert(cd_slot, cd.into());
        self.state = BlobsState::CodeDirectoryAdded;

        Ok(self.code_directory().expect("we just inserted this key"))
    }

    /// Add an alternative code directory.
    ///
    /// This is a wrapper for [Self::add_code_directory()] that has logic for determining the
    /// appropriate slot for the code directory.
    pub fn add_alternative_code_directory(
        &mut self,
        cd: CodeDirectoryBlob<'a>,
    ) -> Result<&CodeDirectoryBlob, AppleCodesignError> {
        let mut our_slot = CodeSigningSlot::AlternateCodeDirectory0;

        for slot in self.blobs.keys() {
            if slot.is_alternative_code_directory() {
                our_slot = CodeSigningSlot::from(u32::from(*slot) + 1);

                if !our_slot.is_alternative_code_directory() {
                    return Err(AppleCodesignError::SignatureBuilder(
                        "no more available alternative code directory slots",
                    ));
                }
            }
        }

        self.add_code_directory(our_slot, cd)
    }

    /// The a CMS signature and register its signature blob.
    ///
    /// `signing_key` and `signing_cert` denote the keypair being used to produce a
    /// cryptographic signature.
    ///
    /// `time_stamp_url` is an optional time-stamp protocol server to use to record
    /// the signature in.
    ///
    /// `certificates` are extra X.509 certificates to register in the signing chain.
    ///
    /// This method errors if called before a code directory is registered.
    pub fn create_cms_signature(
        &mut self,
        signing_key: &dyn KeyInfoSigner,
        signing_cert: &CapturedX509Certificate,
        time_stamp_url: Option<&Url>,
        certificates: impl Iterator<Item = CapturedX509Certificate>,
    ) -> Result<(), AppleCodesignError> {
        let main_cd = self
            .code_directory()
            .ok_or(AppleCodesignError::SignatureBuilder(
                "cannot create CMS signature unless code directory is present",
            ))?;

        if let Some(cn) = signing_cert.subject_common_name() {
            warn!("creating cryptographic signature with certificate {}", cn);
        }

        let mut cdhashes = vec![];
        let mut attributes = vec![];

        for (slot, blob) in &self.blobs {
            if *slot == CodeSigningSlot::CodeDirectory || slot.is_alternative_code_directory() {
                if let BlobData::CodeDirectory(cd) = blob {
                    // plist digests use the native digest of the code directory but always
                    // truncated at 20 bytes.
                    let mut digest = cd.digest_with(cd.digest_type)?;
                    digest.truncate(20);
                    cdhashes.push(plist::Value::Data(digest));

                    // ASN.1 values are a SEQUENCE of (OID, OctetString) with the native
                    // digest.
                    let digest = cd.digest_with(cd.digest_type)?;
                    let alg = DigestAlgorithm::try_from(cd.digest_type)?;

                    attributes.push(AttributeValue::new(bcder::Captured::from_values(
                        bcder::Mode::Der,
                        bcder::encode::sequence((
                            Oid::from(alg).encode_ref(),
                            bcder::OctetString::new(digest.into()).encode_ref(),
                        )),
                    )));
                } else {
                    return Err(AppleCodesignError::SignatureBuilder(
                        "unexpected blob type in code directory slot",
                    ));
                }
            }
        }

        let mut plist_dict = plist::Dictionary::new();
        plist_dict.insert("cdhashes".to_string(), plist::Value::Array(cdhashes));

        let mut plist_xml = vec![];
        plist::Value::from(plist_dict)
            .to_writer_xml(&mut plist_xml)
            .map_err(AppleCodesignError::CodeDirectoryPlist)?;
        // We also need to include a trailing newline to conform with Apple's XML
        // writer.
        plist_xml.push(b'\n');

        let signer = SignerBuilder::new(signing_key, signing_cert.clone())
            .message_id_content(main_cd.to_blob_bytes()?)
            .signed_attribute_octet_string(
                Oid(Bytes::copy_from_slice(CD_DIGESTS_PLIST_OID.as_ref())),
                &plist_xml,
            );

        let signer = signer.signed_attribute(Oid(CD_DIGESTS_OID.as_ref().into()), attributes);

        let signer = if let Some(time_stamp_url) = time_stamp_url {
            info!("Using time-stamp server {}", time_stamp_url);
            signer.time_stamp_url(time_stamp_url.clone())?
        } else {
            signer
        };

        let der = SignedDataBuilder::default()
            // The default is `signed-data`. But Apple appears to use the `data` content-type,
            // in violation of RFC 5652 Section 5, which says `signed-data` should be
            // used when there are signatures.
            .content_type(Oid(OID_ID_DATA.as_ref().into()))
            .signer(signer)
            .certificates(certificates)
            .build_der()?;

        self.blobs.insert(
            CodeSigningSlot::Signature,
            BlobData::BlobWrapper(Box::new(BlobWrapperBlob::from_data_owned(der))),
        );
        self.state = BlobsState::SignatureAdded;

        Ok(())
    }

pub fn add_blob(
    &mut self,
    slot: CodeSigningSlot,
    blob: BlobData<'a>
) -> Result<(), AppleCodesignError>

Register a blob into a slot.

There can only be a single blob per slot. Last write wins.

The code directory and embedded signature cannot be added using this method.

Blobs cannot be registered after a code directory or signature are added, as this would invalidate the signature.

Examples found in repository

src/dmg.rs (line 334)

    pub fn create_superblob<F: Read + Write + Seek>(
        &self,
        settings: &SigningSettings,
        fh: &mut F,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs()? {
            builder.add_blob(slot, blob)?;
        }

        builder.add_code_directory(
            CodeSigningSlot::CodeDirectory,
            self.create_code_directory(settings, fh)?,
        )?;

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

src/macho_signing.rs (line 367)

    pub fn create_superblob(
        &self,
        settings: &SigningSettings,
        macho: &MachOBinary,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs(settings, macho.is_executable())? {
            builder.add_blob(slot, blob)?;
        }

        let code_directory = self.create_code_directory(settings, macho)?;
        info!("code directory version: {}", code_directory.version);

        builder.add_code_directory(CodeSigningSlot::CodeDirectory, code_directory)?;

        if let Some(digests) = settings.extra_digests(SettingsScope::Main) {
            for digest_type in digests {
                // Since everything consults settings for the digest to use, just make a new settings
                // with a different digest.
                let mut alt_settings = settings.clone();
                alt_settings.set_digest_type(*digest_type);

                info!(
                    "adding alternative code directory using digest {:?}",
                    digest_type
                );
                let cd = self.create_code_directory(&alt_settings, macho)?;

                builder.add_alternative_code_directory(cd)?;
            }
        }

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

pub fn add_code_directory(
    &mut self,
    cd_slot: CodeSigningSlot,
    cd: CodeDirectoryBlob<'a>
) -> Result<&CodeDirectoryBlob<'_>, AppleCodesignError>

Register a CodeDirectoryBlob with this builder.

This is the recommended mechanism to register a Code Directory with this instance.

When a code directory is registered, this method will automatically ensure digests of previously registered blobs/slots are present in the code directory. This removes the burden from callers of having to keep the code directory in sync with other registered blobs.

This function accepts the slot to add the code directory to because alternative slots can be registered.

Examples found in repository

src/embedded_signature_builder.rs (line 198)

    pub fn add_alternative_code_directory(
        &mut self,
        cd: CodeDirectoryBlob<'a>,
    ) -> Result<&CodeDirectoryBlob, AppleCodesignError> {
        let mut our_slot = CodeSigningSlot::AlternateCodeDirectory0;

        for slot in self.blobs.keys() {
            if slot.is_alternative_code_directory() {
                our_slot = CodeSigningSlot::from(u32::from(*slot) + 1);

                if !our_slot.is_alternative_code_directory() {
                    return Err(AppleCodesignError::SignatureBuilder(
                        "no more available alternative code directory slots",
                    ));
                }
            }
        }

        self.add_code_directory(our_slot, cd)
    }

src/dmg.rs (lines 337-340)

    pub fn create_superblob<F: Read + Write + Seek>(
        &self,
        settings: &SigningSettings,
        fh: &mut F,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs()? {
            builder.add_blob(slot, blob)?;
        }

        builder.add_code_directory(
            CodeSigningSlot::CodeDirectory,
            self.create_code_directory(settings, fh)?,
        )?;

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

src/macho_signing.rs (line 373)

    pub fn create_superblob(
        &self,
        settings: &SigningSettings,
        macho: &MachOBinary,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs(settings, macho.is_executable())? {
            builder.add_blob(slot, blob)?;
        }

        let code_directory = self.create_code_directory(settings, macho)?;
        info!("code directory version: {}", code_directory.version);

        builder.add_code_directory(CodeSigningSlot::CodeDirectory, code_directory)?;

        if let Some(digests) = settings.extra_digests(SettingsScope::Main) {
            for digest_type in digests {
                // Since everything consults settings for the digest to use, just make a new settings
                // with a different digest.
                let mut alt_settings = settings.clone();
                alt_settings.set_digest_type(*digest_type);

                info!(
                    "adding alternative code directory using digest {:?}",
                    digest_type
                );
                let cd = self.create_code_directory(&alt_settings, macho)?;

                builder.add_alternative_code_directory(cd)?;
            }
        }

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

pub fn add_alternative_code_directory(
    &mut self,
    cd: CodeDirectoryBlob<'a>
) -> Result<&CodeDirectoryBlob<'_>, AppleCodesignError>

Add an alternative code directory.

This is a wrapper for Self::add_code_directory() that has logic for determining the appropriate slot for the code directory.

Examples found in repository

src/macho_signing.rs (line 388)

    pub fn create_superblob(
        &self,
        settings: &SigningSettings,
        macho: &MachOBinary,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs(settings, macho.is_executable())? {
            builder.add_blob(slot, blob)?;
        }

        let code_directory = self.create_code_directory(settings, macho)?;
        info!("code directory version: {}", code_directory.version);

        builder.add_code_directory(CodeSigningSlot::CodeDirectory, code_directory)?;

        if let Some(digests) = settings.extra_digests(SettingsScope::Main) {
            for digest_type in digests {
                // Since everything consults settings for the digest to use, just make a new settings
                // with a different digest.
                let mut alt_settings = settings.clone();
                alt_settings.set_digest_type(*digest_type);

                info!(
                    "adding alternative code directory using digest {:?}",
                    digest_type
                );
                let cd = self.create_code_directory(&alt_settings, macho)?;

                builder.add_alternative_code_directory(cd)?;
            }
        }

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

pub fn create_cms_signature(
    &mut self,
    signing_key: &dyn KeyInfoSigner,
    signing_cert: &CapturedX509Certificate,
    time_stamp_url: Option<&Url>,
    certificates: impl Iterator<Item = CapturedX509Certificate>
) -> Result<(), AppleCodesignError>

The a CMS signature and register its signature blob.

signing_key and signing_cert denote the keypair being used to produce a cryptographic signature.

time_stamp_url is an optional time-stamp protocol server to use to record the signature in.

certificates are extra X.509 certificates to register in the signing chain.

This method errors if called before a code directory is registered.

Examples found in repository

src/dmg.rs (lines 343-348)

    pub fn create_superblob<F: Read + Write + Seek>(
        &self,
        settings: &SigningSettings,
        fh: &mut F,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs()? {
            builder.add_blob(slot, blob)?;
        }

        builder.add_code_directory(
            CodeSigningSlot::CodeDirectory,
            self.create_code_directory(settings, fh)?,
        )?;

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

src/macho_signing.rs (lines 393-398)

    pub fn create_superblob(
        &self,
        settings: &SigningSettings,
        macho: &MachOBinary,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs(settings, macho.is_executable())? {
            builder.add_blob(slot, blob)?;
        }

        let code_directory = self.create_code_directory(settings, macho)?;
        info!("code directory version: {}", code_directory.version);

        builder.add_code_directory(CodeSigningSlot::CodeDirectory, code_directory)?;

        if let Some(digests) = settings.extra_digests(SettingsScope::Main) {
            for digest_type in digests {
                // Since everything consults settings for the digest to use, just make a new settings
                // with a different digest.
                let mut alt_settings = settings.clone();
                alt_settings.set_digest_type(*digest_type);

                info!(
                    "adding alternative code directory using digest {:?}",
                    digest_type
                );
                let cd = self.create_code_directory(&alt_settings, macho)?;

                builder.add_alternative_code_directory(cd)?;
            }
        }

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

pub fn add_notarization_ticket(
    &mut self,
    ticket_data: Vec<u8>
) -> Result<(), AppleCodesignError>

Add notarization ticket data.

This will register a new ticket slot holding the notarization ticket data.

Examples found in repository

src/dmg.rs (line 296)

    pub fn staple_file(
        &self,
        fh: &mut File,
        ticket_data: Vec<u8>,
    ) -> Result<(), AppleCodesignError> {
        warn!(
            "stapling DMG with {} byte notarization ticket",
            ticket_data.len()
        );

        let reader = DmgReader::new(fh)?;
        let koly = reader.koly().clone();
        let signature = reader
            .embedded_signature()?
            .ok_or(AppleCodesignError::DmgStapleNoSignature)?;

        let mut builder = EmbeddedSignatureBuilder::new_for_stapling(signature)?;
        builder.add_notarization_ticket(ticket_data)?;

        let signature = builder.create_superblob()?;

        Self::write_embedded_signature(fh, koly, &signature)
    }

pub fn create_superblob(&self) -> Result<Vec<u8>, AppleCodesignError>

Create the embedded signature “superblob” data.

Examples found in repository

src/dmg.rs (line 298)

    pub fn staple_file(
        &self,
        fh: &mut File,
        ticket_data: Vec<u8>,
    ) -> Result<(), AppleCodesignError> {
        warn!(
            "stapling DMG with {} byte notarization ticket",
            ticket_data.len()
        );

        let reader = DmgReader::new(fh)?;
        let koly = reader.koly().clone();
        let signature = reader
            .embedded_signature()?
            .ok_or(AppleCodesignError::DmgStapleNoSignature)?;

        let mut builder = EmbeddedSignatureBuilder::new_for_stapling(signature)?;
        builder.add_notarization_ticket(ticket_data)?;

        let signature = builder.create_superblob()?;

        Self::write_embedded_signature(fh, koly, &signature)
    }

    fn write_embedded_signature(
        fh: &mut File,
        mut koly: KolyTrailer,
        signature: &[u8],
    ) -> Result<(), AppleCodesignError> {
        warn!("writing {} byte signature", signature.len());
        fh.seek(SeekFrom::Start(koly.offset_after_plist()))?;
        fh.write_all(signature)?;

        koly.code_signature_offset = koly.offset_after_plist();
        koly.code_signature_size = signature.len() as _;

        let mut trailer = [0u8; KOLY_SIZE as usize];
        trailer.pwrite_with(&koly, 0, scroll::BE)?;

        fh.write_all(&trailer)?;

        fh.set_len(koly.code_signature_offset + koly.code_signature_size + KOLY_SIZE as u64)?;

        Ok(())
    }

    /// Create the embedded signature superblob content.
    pub fn create_superblob<F: Read + Write + Seek>(
        &self,
        settings: &SigningSettings,
        fh: &mut F,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs()? {
            builder.add_blob(slot, blob)?;
        }

        builder.add_code_directory(
            CodeSigningSlot::CodeDirectory,
            self.create_code_directory(settings, fh)?,
        )?;

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

src/macho_signing.rs (line 401)

    pub fn create_superblob(
        &self,
        settings: &SigningSettings,
        macho: &MachOBinary,
    ) -> Result<Vec<u8>, AppleCodesignError> {
        let mut builder = EmbeddedSignatureBuilder::default();

        for (slot, blob) in self.create_special_blobs(settings, macho.is_executable())? {
            builder.add_blob(slot, blob)?;
        }

        let code_directory = self.create_code_directory(settings, macho)?;
        info!("code directory version: {}", code_directory.version);

        builder.add_code_directory(CodeSigningSlot::CodeDirectory, code_directory)?;

        if let Some(digests) = settings.extra_digests(SettingsScope::Main) {
            for digest_type in digests {
                // Since everything consults settings for the digest to use, just make a new settings
                // with a different digest.
                let mut alt_settings = settings.clone();
                alt_settings.set_digest_type(*digest_type);

                info!(
                    "adding alternative code directory using digest {:?}",
                    digest_type
                );
                let cd = self.create_code_directory(&alt_settings, macho)?;

                builder.add_alternative_code_directory(cd)?;
            }
        }

        if let Some((signing_key, signing_cert)) = settings.signing_key() {
            builder.create_cms_signature(
                signing_key,
                signing_cert,
                settings.time_stamp_url(),
                settings.certificate_chain().iter().cloned(),
            )?;
        }

        builder.create_superblob()
    }

Trait Implementations

impl<'a> Debug for EmbeddedSignatureBuilder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for EmbeddedSignatureBuilder<'a>

fn default() -> EmbeddedSignatureBuilder<'a>

Returns the “default value” for a type.