Struct SecIdentity

#[repr(C)]
pub struct SecIdentity { /* private fields */ }

Available on crate feature SecBase only.

CFType representing an identity, which contains a SecKeyRef and an associated SecCertificateRef. See SecIdentity.h for details.

See also Apple’s documentation

Implementations

impl SecIdentity

pub unsafe fn create_with_certificate( keychain_or_array: Option<&CFType>, certificate_ref: &SecCertificate, identity_ref: NonNull<*mut SecIdentity>, ) -> i32

Available on crate feature SecIdentity only.

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).

pub unsafe fn copy_certificate( self: &SecIdentity, certificate_ref: NonNull<*mut SecCertificate>, ) -> i32

Available on crate feature SecIdentity only.

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).

pub unsafe fn copy_private_key( self: &SecIdentity, private_key_ref: NonNull<*mut SecKey>, ) -> i32

Available on crate feature SecIdentity only.

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).

pub unsafe fn copy_preference( name: &CFString, key_usage: CSSM_KEYUSE, valid_issuers: Option<&CFArray>, identity: NonNull<*mut SecIdentity>, ) -> i32

👎Deprecated

Available on crate features SecIdentity and cssmconfig and cssmtype only.

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.

pub unsafe fn preferred( name: &CFString, key_usage: Option<&CFArray>, valid_issuers: Option<&CFArray>, ) -> Option<CFRetained<SecIdentity>>

Available on crate feature SecIdentity only.

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.

pub unsafe fn set_preference( self: &SecIdentity, name: &CFString, key_usage: CSSM_KEYUSE, ) -> i32

👎Deprecated

Available on crate features SecIdentity and cssmconfig and cssmtype only.

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.

pub unsafe fn set_preferred( identity: Option<&SecIdentity>, name: &CFString, key_usage: Option<&CFArray>, ) -> i32

Available on crate feature SecIdentity only.

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.

pub unsafe fn copy_system_identity( domain: &CFString, id_ref: NonNull<*mut SecIdentity>, actual_domain: *mut *const CFString, ) -> i32

Available on crate feature SecIdentity only.

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.

pub unsafe fn set_system_identity( domain: &CFString, id_ref: Option<&SecIdentity>, ) -> i32

Available on crate feature SecIdentity only.

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.

Methods from Deref<Target = CFType>

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: ConcreteType,

Available on crate feature SecCustomTransform only.

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

pub fn retain_count(&self) -> usize

Available on crate feature SecCustomTransform only.

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.

Trait Implementations

impl AsRef<AnyObject> for SecIdentity

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CFType> for SecIdentity

fn as_ref(&self) -> &CFType

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<SecIdentity> for SecIdentity

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for SecIdentity

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for SecIdentity

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for SecIdentity

Available on crate feature SecIdentity only.

fn type_id() -> CFTypeID

Returns the type identifier of SecIdentity instances.

Returns: The CFTypeID of SecIdentity instances.

impl Debug for SecIdentity

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

Formats the value using the given formatter.

impl Deref for SecIdentity

type Target = CFType

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for SecIdentity

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for SecIdentity

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for SecIdentity

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for SecIdentity

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type.

impl Type for SecIdentity

fn retain(&self) -> CFRetained<Self>

where Self: Sized,

Increment the reference count of the receiver.

fn as_concrete_TypeRef(&self) -> &Self

👎Deprecated: this is redundant

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::retain

Helper for easier transition from the core-foundation crate.

fn as_CFTypeRef(&self) -> &CFType

where Self: AsRef<CFType>,

👎Deprecated: this is redundant (CF types deref to CFType)

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::from_raw

Helper for easier transition from the core-foundation crate.

impl Eq for SecIdentity