objc2_security/generated/

SecIdentity.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ptr::NonNull;
use objc2_core_foundation::*;

use crate::*;

#[cfg(feature = "SecBase")]
unsafe impl ConcreteType for SecIdentity {
    /// Returns the type identifier of SecIdentity instances.
    ///
    /// Returns: The CFTypeID of SecIdentity instances.
    #[doc(alias = "SecIdentityGetTypeID")]
    #[inline]
    fn type_id() -> CFTypeID {
        extern "C-unwind" {
            fn SecIdentityGetTypeID() -> CFTypeID;
        }
        unsafe { SecIdentityGetTypeID() }
    }
}

#[cfg(feature = "SecBase")]
impl SecIdentity {
    /// create a new identity object from the provided certificate and its associated private key.
    ///
    /// Parameter `allocator`: CFAllocator to allocate the identity object. Pass NULL to use the default allocator.
    ///
    /// Parameter `certificate`: A certificate reference.
    ///
    /// Parameter `privateKey`: A private key reference.
    ///
    /// Returns: An identity reference.
    ///
    /// This interface returns null if the private does not key correspond to the public key in the certifcate.
    #[doc(alias = "SecIdentityCreate")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn new(
        allocator: Option<&CFAllocator>,
        certificate: &SecCertificate,
        private_key: &SecKey,
    ) -> Option<CFRetained<SecIdentity>> {
        extern "C-unwind" {
            fn SecIdentityCreate(
                allocator: Option<&CFAllocator>,
                certificate: &SecCertificate,
                private_key: &SecKey,
            ) -> Option<NonNull<SecIdentity>>;
        }
        let ret = unsafe { SecIdentityCreate(allocator, certificate, private_key) };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// Creates a new identity reference for the given certificate, assuming the associated private key is in one of the specified keychains.
    ///
    /// Parameter `keychainOrArray`: A reference to an array of keychains to search, a single keychain, or NULL to search the user's default keychain search list.
    ///
    /// Parameter `certificateRef`: A certificate reference.
    ///
    /// Parameter `identityRef`: On return, an identity reference. You are responsible for releasing this reference by calling the CFRelease function.
    ///
    /// Returns: A result code. See "Security Error Codes" (SecBase.h).
    ///
    /// # Safety
    ///
    /// - `keychain_or_array` should be of the correct type.
    /// - `identity_ref` must be a valid pointer.
    #[doc(alias = "SecIdentityCreateWithCertificate")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn create_with_certificate(
        keychain_or_array: Option<&CFType>,
        certificate_ref: &SecCertificate,
        identity_ref: NonNull<*mut SecIdentity>,
    ) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentityCreateWithCertificate(
                keychain_or_array: Option<&CFType>,
                certificate_ref: &SecCertificate,
                identity_ref: NonNull<*mut SecIdentity>,
            ) -> OSStatus;
        }
        unsafe {
            SecIdentityCreateWithCertificate(keychain_or_array, certificate_ref, identity_ref)
        }
    }

    /// Returns a reference to a certificate for the given identity
    /// reference.
    ///
    /// Parameter `identityRef`: An identity reference.
    ///
    /// Parameter `certificateRef`: On return, a pointer to the found certificate
    /// reference. You are responsible for releasing this reference by calling
    /// the CFRelease function.
    ///
    /// Returns: A result code. See "Security Error Codes" (SecBase.h).
    ///
    /// # Safety
    ///
    /// `certificate_ref` must be a valid pointer.
    #[doc(alias = "SecIdentityCopyCertificate")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn copy_certificate(
        &self,
        certificate_ref: NonNull<*mut SecCertificate>,
    ) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentityCopyCertificate(
                identity_ref: &SecIdentity,
                certificate_ref: NonNull<*mut SecCertificate>,
            ) -> OSStatus;
        }
        unsafe { SecIdentityCopyCertificate(self, certificate_ref) }
    }

    /// Returns the private key associated with an identity.
    ///
    /// Parameter `identityRef`: An identity reference.
    ///
    /// Parameter `privateKeyRef`: On return, a pointer to the private key for the given
    /// identity. On iOS, the private key must be of class type kSecAppleKeyItemClass.
    /// You are responsible for releasing this reference by calling the CFRelease function.
    ///
    /// Returns: A result code. See "Security Error Codes" (SecBase.h).
    ///
    /// # Safety
    ///
    /// `private_key_ref` must be a valid pointer.
    #[doc(alias = "SecIdentityCopyPrivateKey")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn copy_private_key(&self, private_key_ref: NonNull<*mut SecKey>) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentityCopyPrivateKey(
                identity_ref: &SecIdentity,
                private_key_ref: NonNull<*mut SecKey>,
            ) -> OSStatus;
        }
        unsafe { SecIdentityCopyPrivateKey(self, private_key_ref) }
    }

    /// Returns the preferred identity for the specified name and key usage, optionally limiting the result to an identity issued by a certificate whose subject is one of the distinguished names in validIssuers. If a preferred identity does not exist, NULL is returned.
    ///
    /// Parameter `name`: A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies the service requiring an identity.
    ///
    /// Parameter `keyUsage`: A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to ignore this parameter.
    ///
    /// Parameter `validIssuers`: (optional) An array of CFDataRef instances whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames (SecureTransport.h). Pass NULL if any issuer is allowed.
    ///
    /// Parameter `identity`: On return, a reference to the preferred identity, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.
    ///
    /// Returns: A result code. See "Security Error Codes" (SecBase.h).
    ///
    /// This API is deprecated in 10.7. Please use the SecIdentityCopyPreferred API instead.
    ///
    /// # Safety
    ///
    /// - `valid_issuers` generic must be of the correct type.
    /// - `identity` must be a valid pointer.
    #[doc(alias = "SecIdentityCopyPreference")]
    #[cfg(all(feature = "SecBase", feature = "cssmconfig", feature = "cssmtype"))]
    #[deprecated]
    #[inline]
    pub unsafe fn copy_preference(
        name: &CFString,
        key_usage: CSSM_KEYUSE,
        valid_issuers: Option<&CFArray>,
        identity: NonNull<*mut SecIdentity>,
    ) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentityCopyPreference(
                name: &CFString,
                key_usage: CSSM_KEYUSE,
                valid_issuers: Option<&CFArray>,
                identity: NonNull<*mut SecIdentity>,
            ) -> OSStatus;
        }
        unsafe { SecIdentityCopyPreference(name, key_usage, valid_issuers, identity) }
    }

    /// Returns the preferred identity for the specified name and key usage, optionally limiting the result to an identity issued by a certificate whose subject is one of the distinguished names in validIssuers. If a preferred identity does not exist, NULL is returned.
    ///
    /// Parameter `name`: A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies the service requiring an identity.
    ///
    /// Parameter `keyUsage`: A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
    ///
    /// Parameter `validIssuers`: (optional) An array of CFDataRef instances whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames (SecureTransport.h). Pass NULL if any issuer is allowed.
    ///
    /// Returns: An identity or NULL, if the preferred identity has not been set. Your code should then typically perform a search for possible identities using the SecItem APIs.
    ///
    /// If a preferred identity has not been set for the supplied name, the returned identity reference will be NULL. Your code should then perform a search for possible identities, using the SecItemCopyMatching API. Note: in versions of macOS prior to 11.3, identity preferences are shared between processes running as the same user. Starting in 11.3, URI names are considered per-application preferences. An identity preference for a URI name may not be found if the calling application is different from the one which set the preference with SecIdentitySetPreferred.
    ///
    /// # Safety
    ///
    /// - `key_usage` generic must be of the correct type.
    /// - `valid_issuers` generic must be of the correct type.
    #[doc(alias = "SecIdentityCopyPreferred")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn preferred(
        name: &CFString,
        key_usage: Option<&CFArray>,
        valid_issuers: Option<&CFArray>,
    ) -> Option<CFRetained<SecIdentity>> {
        extern "C-unwind" {
            fn SecIdentityCopyPreferred(
                name: &CFString,
                key_usage: Option<&CFArray>,
                valid_issuers: Option<&CFArray>,
            ) -> Option<NonNull<SecIdentity>>;
        }
        let ret = unsafe { SecIdentityCopyPreferred(name, key_usage, valid_issuers) };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// Sets the preferred identity for the specified name and key usage.
    ///
    /// Parameter `identity`: A reference to the identity which will be preferred.
    ///
    /// Parameter `name`: A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
    ///
    /// Parameter `keyUsage`: A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to specify any key usage.
    ///
    /// Returns: A result code. See "Security Error Codes" (SecBase.h).
    ///
    /// This API is deprecated in 10.7. Please use the SecIdentitySetPreferred API instead.
    #[doc(alias = "SecIdentitySetPreference")]
    #[cfg(all(feature = "SecBase", feature = "cssmconfig", feature = "cssmtype"))]
    #[deprecated]
    #[inline]
    pub unsafe fn set_preference(&self, name: &CFString, key_usage: CSSM_KEYUSE) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentitySetPreference(
                identity: &SecIdentity,
                name: &CFString,
                key_usage: CSSM_KEYUSE,
            ) -> OSStatus;
        }
        unsafe { SecIdentitySetPreference(self, name, key_usage) }
    }

    /// Sets the preferred identity for the specified name and key usage.
    ///
    /// Parameter `identity`: A reference to the identity which will be preferred. If NULL is passed, any existing preference for the specified name is cleared instead.
    ///
    /// Parameter `name`: A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
    ///
    /// Parameter `keyUsage`: A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to specify any key usage. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
    ///
    /// Returns: A result code. See "Security Error Codes" (SecBase.h).
    ///
    /// Note: in versions of macOS prior to 11.3, identity preferences are shared between processes running as the same user. Starting in 11.3, URI names are considered per-application preferences. An identity preference for a URI name will be scoped to the application which created it, such that a subsequent call to SecIdentityCopyPreferred will only return it for that same application.
    ///
    /// # Safety
    ///
    /// `key_usage` generic must be of the correct type.
    #[doc(alias = "SecIdentitySetPreferred")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn set_preferred(
        identity: Option<&SecIdentity>,
        name: &CFString,
        key_usage: Option<&CFArray>,
    ) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentitySetPreferred(
                identity: Option<&SecIdentity>,
                name: &CFString,
                key_usage: Option<&CFArray>,
            ) -> OSStatus;
        }
        unsafe { SecIdentitySetPreferred(identity, name, key_usage) }
    }

    /// Obtain the system-wide SecIdentityRef associated with
    /// a specified domain.
    ///
    /// Parameter `domain`: Identifies the SecIdentityRef to be obtained, typically
    /// in the form "com.apple.subdomain...".
    ///
    /// Parameter `idRef`: On return, the system SecIdentityRef assicated with
    /// the specified domain. Caller must CFRelease this when
    /// finished with it.
    ///
    /// Parameter `actualDomain`: (optional) The actual domain name of the
    /// the returned identity is returned here. This
    /// may be different from the requested domain.
    ///
    /// Returns: A result code.  See "Security Error Codes" (SecBase.h).
    ///
    /// If no system SecIdentityRef exists for the specified
    /// domain, a domain-specific alternate may be returned
    /// instead, typically (but not exclusively) the
    /// kSecIdentityDomainDefault SecIdentityRef.
    ///
    /// # Safety
    ///
    /// - `id_ref` must be a valid pointer.
    /// - `actual_domain` must be a valid pointer or null.
    #[doc(alias = "SecIdentityCopySystemIdentity")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn copy_system_identity(
        domain: &CFString,
        id_ref: NonNull<*mut SecIdentity>,
        actual_domain: *mut *const CFString,
    ) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentityCopySystemIdentity(
                domain: &CFString,
                id_ref: NonNull<*mut SecIdentity>,
                actual_domain: *mut *const CFString,
            ) -> OSStatus;
        }
        unsafe { SecIdentityCopySystemIdentity(domain, id_ref, actual_domain) }
    }

    /// Assign the supplied SecIdentityRef to the specified
    /// domain.
    ///
    /// Parameter `domain`: Identifies the domain to which the specified
    /// SecIdentityRef will be assigned.
    ///
    /// Parameter `idRef`: (optional) The identity to be assigned to the specified
    /// domain. Pass NULL to delete a possible entry for the specified
    /// domain; in this case, it is not an error if no identity
    /// exists for the specified domain.
    ///
    /// Returns: A result code.  See "Security Error Codes" (SecBase.h).
    ///
    /// The caller must be running as root.
    #[doc(alias = "SecIdentitySetSystemIdentity")]
    #[cfg(feature = "SecBase")]
    #[inline]
    pub unsafe fn set_system_identity(domain: &CFString, id_ref: Option<&SecIdentity>) -> OSStatus {
        extern "C-unwind" {
            fn SecIdentitySetSystemIdentity(
                domain: &CFString,
                id_ref: Option<&SecIdentity>,
            ) -> OSStatus;
        }
        unsafe { SecIdentitySetSystemIdentity(domain, id_ref) }
    }
}

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/security/ksecidentitydomaindefault?language=objc)
    pub static kSecIdentityDomainDefault: &'static CFString;
}

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/security/ksecidentitydomainkerberoskdc?language=objc)
    pub static kSecIdentityDomainKerberosKDC: &'static CFString;
}

#[cfg(feature = "SecBase")]
#[deprecated = "renamed to `SecIdentity::new`"]
#[inline]
pub unsafe extern "C-unwind" fn SecIdentityCreate(
    allocator: Option<&CFAllocator>,
    certificate: &SecCertificate,
    private_key: &SecKey,
) -> Option<CFRetained<SecIdentity>> {
    extern "C-unwind" {
        fn SecIdentityCreate(
            allocator: Option<&CFAllocator>,
            certificate: &SecCertificate,
            private_key: &SecKey,
        ) -> Option<NonNull<SecIdentity>>;
    }
    let ret = unsafe { SecIdentityCreate(allocator, certificate, private_key) };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

extern "C-unwind" {
    #[cfg(feature = "SecBase")]
    #[deprecated = "renamed to `SecIdentity::create_with_certificate`"]
    pub fn SecIdentityCreateWithCertificate(
        keychain_or_array: Option<&CFType>,
        certificate_ref: &SecCertificate,
        identity_ref: NonNull<*mut SecIdentity>,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[cfg(feature = "SecBase")]
    #[deprecated = "renamed to `SecIdentity::copy_certificate`"]
    pub fn SecIdentityCopyCertificate(
        identity_ref: &SecIdentity,
        certificate_ref: NonNull<*mut SecCertificate>,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[cfg(feature = "SecBase")]
    #[deprecated = "renamed to `SecIdentity::copy_private_key`"]
    pub fn SecIdentityCopyPrivateKey(
        identity_ref: &SecIdentity,
        private_key_ref: NonNull<*mut SecKey>,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[cfg(all(feature = "SecBase", feature = "cssmconfig", feature = "cssmtype"))]
    #[deprecated = "renamed to `SecIdentity::copy_preference`"]
    pub fn SecIdentityCopyPreference(
        name: &CFString,
        key_usage: CSSM_KEYUSE,
        valid_issuers: Option<&CFArray>,
        identity: NonNull<*mut SecIdentity>,
    ) -> OSStatus;
}

#[cfg(feature = "SecBase")]
#[deprecated = "renamed to `SecIdentity::preferred`"]
#[inline]
pub unsafe extern "C-unwind" fn SecIdentityCopyPreferred(
    name: &CFString,
    key_usage: Option<&CFArray>,
    valid_issuers: Option<&CFArray>,
) -> Option<CFRetained<SecIdentity>> {
    extern "C-unwind" {
        fn SecIdentityCopyPreferred(
            name: &CFString,
            key_usage: Option<&CFArray>,
            valid_issuers: Option<&CFArray>,
        ) -> Option<NonNull<SecIdentity>>;
    }
    let ret = unsafe { SecIdentityCopyPreferred(name, key_usage, valid_issuers) };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

extern "C-unwind" {
    #[cfg(all(feature = "SecBase", feature = "cssmconfig", feature = "cssmtype"))]
    #[deprecated = "renamed to `SecIdentity::set_preference`"]
    pub fn SecIdentitySetPreference(
        identity: &SecIdentity,
        name: &CFString,
        key_usage: CSSM_KEYUSE,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[cfg(feature = "SecBase")]
    #[deprecated = "renamed to `SecIdentity::set_preferred`"]
    pub fn SecIdentitySetPreferred(
        identity: Option<&SecIdentity>,
        name: &CFString,
        key_usage: Option<&CFArray>,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[cfg(feature = "SecBase")]
    #[deprecated = "renamed to `SecIdentity::copy_system_identity`"]
    pub fn SecIdentityCopySystemIdentity(
        domain: &CFString,
        id_ref: NonNull<*mut SecIdentity>,
        actual_domain: *mut *const CFString,
    ) -> OSStatus;
}

extern "C-unwind" {
    #[cfg(feature = "SecBase")]
    #[deprecated = "renamed to `SecIdentity::set_system_identity`"]
    pub fn SecIdentitySetSystemIdentity(
        domain: &CFString,
        id_ref: Option<&SecIdentity>,
    ) -> OSStatus;
}