Struct SecCertificate

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

Available on crate feature SecBase only.

CFType representing a X.509 certificate. See SecCertificate.h for details.

See also Apple’s documentation

Implementations

impl SecCertificate

pub unsafe fn with_data( allocator: Option<&CFAllocator>, data: &CFData, ) -> Option<CFRetained<SecCertificate>>

Available on crate feature SecCertificate only.

Create a certificate given it’s DER representation as a CFData.

Parameter allocator: CFAllocator to allocate the certificate with.

Parameter data: DER encoded X.509 certificate.

Returns: Return NULL if the passed-in data is not a valid DER-encoded X.509 certificate, return a SecCertificateRef otherwise.

pub unsafe fn data(self: &SecCertificate) -> CFRetained<CFData>

Available on crate feature SecCertificate only.

Return the DER representation of an X.509 certificate.

Parameter certificate: SecCertificate object created with SecCertificateCreateWithData().

Returns: DER encoded X.509 certificate.

pub unsafe fn subject_summary( self: &SecCertificate, ) -> Option<CFRetained<CFString>>

Available on crate feature SecCertificate only.

Return a simple string which hopefully represents a human understandable summary.

Parameter certificate: A reference to the certificate from which to derive the subject summary string.

All the data in this string comes from the certificate itself and thus it’s in whatever language the certificate itself is in.

Returns: A CFStringRef which the caller should CFRelease() once it’s no longer needed.

pub unsafe fn copy_common_name( self: &SecCertificate, common_name: NonNull<*const CFString>, ) -> i32

Available on crate feature SecCertificate only.

Retrieves the common name of the subject of a given certificate.

Parameter certificate: A reference to the certificate from which to retrieve the common name.

Parameter commonName: On return, a reference to the common name. Your code must release this reference by calling the CFRelease function.

Returns: A result code. See “Security Error Codes” (SecBase.h).

All the data in this string comes from the certificate itself, and thus it’s in whatever language the certificate itself is in. Note that the certificate’s common name field may not be present, or may be inadequate to describe the certificate; for display purposes, you should consider using SecCertificateCopySubjectSummary instead of this function.

pub unsafe fn copy_email_addresses( self: &SecCertificate, email_addresses: NonNull<*const CFArray>, ) -> i32

Available on crate feature SecCertificate only.

Returns an array of zero or more email addresses for the subject of a given certificate.

Parameter certificate: A reference to the certificate from which to retrieve the email addresses.

Parameter emailAddresses: On return, an array of zero or more CFStringRef elements corresponding to each email address found. Your code must release this array reference by calling the CFRelease function.

Returns: A result code. See “Security Error Codes” (SecBase.h).

pub unsafe fn normalized_issuer_sequence( self: &SecCertificate, ) -> Option<CFRetained<CFData>>

Available on crate feature SecCertificate only.

Return the certificate’s normalized issuer

Parameter certificate: The certificate from which to get values

The issuer is a sequence in the format used by SecItemCopyMatching. The content returned is a DER-encoded X.509 distinguished name. For a display version of the issuer, call SecCertificateCopyValues. The caller must CFRelease the value returned.

pub unsafe fn normalized_subject_sequence( self: &SecCertificate, ) -> Option<CFRetained<CFData>>

Available on crate feature SecCertificate only.

Return the certificate’s normalized subject

Parameter certificate: The certificate from which to get values

The subject is a sequence in the format used by SecItemCopyMatching. The content returned is a DER-encoded X.509 distinguished name. For a display version of the subject, call SecCertificateCopyValues. The caller must CFRelease the value returned.

pub unsafe fn key(self: &SecCertificate) -> Option<CFRetained<SecKey>>

Available on crate feature SecCertificate only.

Retrieves the public key for a given certificate.

Parameter certificate: A reference to the certificate from which to retrieve the public key.

Returns: A reference to the public key for the specified certificate. Your code must release this reference by calling the CFRelease function. If the public key has an encoding issue or uses an unsupported algorithm, the returned reference will be null.

RSA and ECDSA public keys are supported. All other public key algorithms are unsupported.

pub unsafe fn copy_public_key( self: &SecCertificate, key: NonNull<*mut SecKey>, ) -> i32

👎Deprecated

Available on crate feature SecCertificate only.

Retrieves the public key for a given certificate.

Parameter certificate: A reference to the certificate from which to retrieve the public key.

Parameter key: On return, a reference to the public key for the specified certificate. Your code must release this reference by calling the CFRelease function.

Returns: A result code. See “Security Error Codes” (SecBase.h).

NOTE: Deprecated in macOS 10.14; use SecCertificateCopyKey instead for cross-platform availability.

pub unsafe fn serial_number_data( self: &SecCertificate, error: *mut *mut CFError, ) -> Option<CFRetained<CFData>>

Available on crate feature SecCertificate only.

Return the certificate’s serial number.

Parameter certificate: The certificate from which to get values.

Parameter error: An optional pointer to a CFErrorRef which will be set on return from the function if an error occurred. If not NULL, the caller is responsible for releasing the CFErrorRef.

Return the content of a DER-encoded integer (without the tag and length fields) for this certificate’s serial number. The caller must CFRelease the value returned.

pub unsafe fn not_valid_before_date( self: &SecCertificate, ) -> Option<CFRetained<CFDate>>

Available on crate feature SecCertificate only.

Obtain the starting date of the given certificate.

Parameter certificate: The certificate from which to get values.

Returns: Returns the absolute time at which the given certificate becomes valid, or NULL if this value could not be obtained. The caller must CFRelease the value returned.

pub unsafe fn not_valid_after_date( self: &SecCertificate, ) -> Option<CFRetained<CFDate>>

Available on crate feature SecCertificate only.

Obtain the expiration date of the given certificate.

Parameter certificate: The certificate from which to get values.

Returns: Returns the absolute time at which the given certificate expires, or NULL if this value could not be obtained. The caller must CFRelease the value returned.

pub unsafe fn serial_number( self: &SecCertificate, error: *mut *mut CFError, ) -> Option<CFRetained<CFData>>

👎Deprecated

Available on crate feature SecCertificate only.

Return the certificate’s serial number.

Parameter certificate: The certificate from which to get values.

Parameter error: An optional pointer to a CFErrorRef which will be set on return from the function if an error occurred. If not NULL, the caller is responsible for releasing the CFErrorRef.

Return the content of a DER-encoded integer (without the tag and length fields) for this certificate’s serial number. The caller must CFRelease the value returned. NOTE: Deprecated in macOS 10.13; use SecCertificateCopySerialNumberData instead for cross-platform availability.

impl SecCertificate

pub unsafe fn create_from_data( data: NonNull<SecAsn1Item>, type: CSSM_CERT_TYPE, encoding: CSSM_CERT_ENCODING, certificate: NonNull<*mut SecCertificate>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and SecAsn1Types and cssmconfig and cssmtype only.

Creates a certificate based on the input data, type, and encoding.

Parameter data: A pointer to the certificate data.

Parameter type: The certificate type as defined in cssmtype.h.

Parameter encoding: The certificate encoding as defined in cssmtype.h.

Parameter certificate: On return, a reference to the newly created certificate.

Returns: A result code. See “Security Error Codes” (SecBase.h).

This API is deprecated in 10.7 Please use the SecCertificateCreateWithData API instead.

pub unsafe fn add_to_keychain( self: &SecCertificate, keychain: Option<&SecKeychain>, ) -> i32

Available on crate feature SecCertificate only.

Adds a certificate to the specified keychain.

Parameter certificate: A reference to a certificate.

Parameter keychain: A reference to the keychain in which to add the certificate. Pass NULL to add the certificate to the default keychain.

Returns: A result code. See “Security Error Codes” (SecBase.h).

This function is successful only if the certificate was created using the SecCertificateCreateFromData or SecCertificateCreateWithData functions, and the certificate has not yet been added to the specified keychain.

pub unsafe fn get_data(self: &SecCertificate, data: CSSM_DATA_PTR) -> i32

👎Deprecated

Available on crate features SecCertificate and SecAsn1Types and cssmtype only.

Retrieves the data for a given certificate.

Parameter certificate: A reference to the certificate from which to retrieve the data.

Parameter data: On return, the CSSM_DATA structure pointed to by data is filled in. You must allocate the space for a CSSM_DATA structure before calling this function. This data pointer is only guaranteed to remain valid as long as the certificate remains unchanged and valid.

Returns: A result code. See “Security Error Codes” (SecBase.h).

This API is deprecated in 10.7. Please use the SecCertificateCopyData API instead.

pub unsafe fn type( self: &SecCertificate, certificate_type: NonNull<CSSM_CERT_TYPE>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and cssmconfig and cssmtype only.

Retrieves the type for a given certificate.

Parameter certificate: A reference to the certificate from which to obtain the type.

Parameter certificateType: On return, the certificate type of the certificate. Certificate types are defined in cssmtype.h.

Returns: A result code. See “Security Error Codes” (SecBase.h).

This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.

pub unsafe fn subject( self: &SecCertificate, subject: NonNull<*const CSSM_X509_NAME>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and SecAsn1Types and cssmconfig and x509defs only.

Retrieves the subject name for a given certificate.

Parameter certificate: A reference to the certificate from which to obtain the subject name.

Parameter subject: On return, a pointer to a CSSM_X509_NAME struct which contains the subject’s X.509 name (x509defs.h). This pointer remains valid until the certificate reference is released. The caller should not attempt to free this pointer.

Returns: A result code. See “Security Error Codes” (SecBase.h).

Prior to Mac OS X 10.5, this function did not return any output in the subject parameter. Your code should check the returned pointer value (in addition to the function result) before attempting to use it. For example: const CSSM_X509_NAME *subject = NULL; OSStatus status = SecCertificateGetSubject(certificate, &subject ); if ( (status == errSecSuccess) & & (subject != NULL) ) { // subject is valid } This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.

pub unsafe fn issuer( self: &SecCertificate, issuer: NonNull<*const CSSM_X509_NAME>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and SecAsn1Types and cssmconfig and x509defs only.

Retrieves the issuer name for a given certificate.

Parameter certificate: A reference to the certificate from which to obtain the issuer name.

Parameter issuer: On return, a pointer to a CSSM_X509_NAME struct which contains the issuer’s X.509 name (x509defs.h). This pointer remains valid until the certificate reference is released. The caller should not attempt to free this pointer.

Returns: A result code. See “Security Error Codes” (SecBase.h).

Prior to Mac OS X 10.5, this function did not return any output in the issuer parameter. Your code should check the returned pointer value (in addition to the function result) before attempting to use it. For example: const CSSM_X509_NAME *issuer = NULL; OSStatus status = SecCertificateGetIssuer(certificate, &issuer ); if ( (status == errSecSuccess) & & (issuer != NULL) ) { // issuer is valid } This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.

pub unsafe fn cl_handle( self: &SecCertificate, cl_handle: NonNull<CSSM_CL_HANDLE>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and cssmconfig and cssmtype only.

Retrieves the certificate library handle for a given certificate.

Parameter certificate: A reference to the certificate from which to obtain the certificate library handle.

Parameter clHandle: On return, the certificate library handle of the given certificate. This handle remains valid at least as long as the certificate does.

Returns: A result code. See “Security Error Codes” (SecBase.h).

This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.

pub unsafe fn algorithm_id( self: &SecCertificate, algid: NonNull<*const SecAsn1AlgId>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and SecAsn1Types only.

Retrieves the algorithm identifier for a given certificate.

Parameter certificate: A reference to the certificate from which to retrieve the algorithm identifier.

Parameter algid: On return, a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER struct which identifies the algorithm for this certificate (x509defs.h). This pointer remains valid until the certificate reference is released. The caller should not attempt to free this pointer.

Returns: A result code. See “Security Error Codes” (SecBase.h). discussion This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.

pub unsafe fn copy_preference( name: &CFString, key_usage: uint32, certificate: NonNull<*mut SecCertificate>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and cssmconfig only.

Returns the preferred certificate for the specified name and key usage. If a preferred certificate does not exist for the specified name and key usage, NULL is returned.

Parameter name: A string containing an email address (RFC822) or other name for which a preferred certificate is requested.

Parameter keyUsage: A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to ignore this parameter.

Parameter certificate: On return, a reference to the preferred certificate, 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 function will typically be used to obtain the preferred encryption certificate for an email recipient. This API is deprecated in 10.7. Please use the SecCertificateCopyPreferred API instead.

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

Available on crate feature SecCertificate only.

Returns the preferred certificate for the specified name and key usage. If a preferred certificate does not exist for the specified name and key usage, NULL is returned.

Parameter name: A string containing an email address (RFC822) or other name for which a preferred certificate is requested.

Parameter keyUsage: A CFArrayRef value, containing items defined in SecItem.h Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)

Returns: On return, a reference to the preferred certificate, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.

This function will typically be used to obtain the preferred encryption certificate for an email recipient. If a preferred certificate has not been set for the supplied name, the returned reference will be NULL. Your code should then perform a search for possible certificates, using the SecItemCopyMatching API.

pub unsafe fn set_preference( self: &SecCertificate, name: &CFString, key_usage: uint32, date: Option<&CFDate>, ) -> i32

👎Deprecated

Available on crate features SecCertificate and cssmconfig only.

Sets the preferred certificate for a specified name, key usage, and date.

Parameter certificate: A reference to the certificate which will be preferred.

Parameter name: A string containing an email address (RFC822) or other name for which a preferred certificate will be associated.

Parameter keyUsage: A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to avoid specifying a particular key usage.

Parameter date: (optional) A date reference. If supplied, the preferred certificate will be changed only if this date is later than the currently saved setting. Pass NULL if this preference should not be restricted by date.

Returns: A result code. See “Security Error Codes” (SecBase.h).

This function will typically be used to set the preferred encryption certificate for an email recipient, either manually (when encrypting email to a recipient) or automatically upon receipt of encrypted email. This API is deprecated in 10.7. Plese use the SecCertificateSetPreferred API instead.

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

Available on crate feature SecCertificate only.

Sets the preferred certificate for a specified name and optional key usage.

Parameter certificate: A reference to the preferred certificate. If NULL is passed, any existing preference for the specified name is cleared instead.

Parameter name: A string containing an email address (RFC822) or other name for which a preferred certificate will be associated.

Parameter keyUsage: A CFArrayRef value, containing items defined in SecItem.h Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)

Returns: A result code. See “Security Error Codes” (SecBase.h).

This function will typically be used to set the preferred encryption certificate for an email recipient, either manually (when encrypting email to a recipient) or automatically upon receipt of encrypted email.

impl SecCertificate

pub unsafe fn values( self: &SecCertificate, keys: Option<&CFArray>, error: *mut *mut CFError, ) -> Option<CFRetained<CFDictionary>>

Available on crate feature SecCertificate only.

Creates a dictionary that represents a certificate’s contents.

Parameter certificate: The certificate from which to get values

Parameter keys: An array of string OID values, or NULL. If present, this is the subset of values from the certificate to return. If NULL, all values will be returned. Only OIDs that are top level keys in the returned dictionary can be specified. Unknown OIDs are ignored.

Parameter error: An optional pointer to a CFErrorRef. This value is set if an error occurred. If not NULL the caller is responsible for releasing the CFErrorRef.

The keys array will contain all of the keys used in the returned dictionary. The top level keys in the returned dictionary are OIDs, many of which are found in SecCertificateOIDs.h. Each entry that is returned is itself a dictionary with four entries, whose keys are kSecPropertyKeyType, kSecPropertyKeyLabel, kSecPropertyKeyLocalizedLabel, kSecPropertyKeyValue. The label entries may contain a descriptive (localized) string, or an OID string. The kSecPropertyKeyType describes the type in the value entry. The value entry may be any CFType, although it is usually a CFStringRef, CFArrayRef or a CFDictionaryRef.

pub unsafe fn long_description( alloc: Option<&CFAllocator>, certificate: &SecCertificate, error: *mut *mut CFError, ) -> Option<CFRetained<CFString>>

Available on crate feature SecCertificate only.

Return the long description of a certificate

Parameter alloc: The CFAllocator which should be used to allocate memory for the dictionary and its storage for values. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

Parameter certificate: The certificate from which to retrieve the long description

Parameter error: An optional pointer to a CFErrorRef. This value is set if an error occurred. If not NULL the caller is responsible for releasing the CFErrorRef.

Returns: A CFStringRef of the long description or NULL. If NULL and the error parameter is supplied the error will be returned in the error parameter

Note that the format of this string may change in the future

pub unsafe fn short_description( alloc: Option<&CFAllocator>, certificate: &SecCertificate, error: *mut *mut CFError, ) -> Option<CFRetained<CFString>>

Available on crate feature SecCertificate only.

Return the short description of a certificate

Parameter alloc: The CFAllocator which should be used to allocate memory for the dictionary and its storage for values. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

Parameter certificate: The certificate from which to retrieve the short description

Parameter error: An optional pointer to a CFErrorRef. This value is set if an error occurred. If not NULL the caller is responsible for releasing the CFErrorRef.

Returns: A CFStringRef of the short description or NULL. If NULL and the error parameter is supplied the error will be returned in the error parameter

Note that the format of this string may change in the future

pub unsafe fn normalized_issuer_content( self: &SecCertificate, error: *mut *mut CFError, ) -> Option<CFRetained<CFData>>

👎Deprecated: SecCertificateCopyNormalizedIssuerContent is deprecated. Use SecCertificateCopyNormalizedIssuerSequence instead.

Available on crate feature SecCertificate only.

Return the certificate’s normalized issuer

Parameter certificate: The certificate from which to get values

Parameter error: An optional pointer to a CFErrorRef. This value is set if an error occurred. If not NULL the caller is responsible for releasing the CFErrorRef.

The issuer is a sequence in the format used by SecItemCopyMatching. The content returned is a DER-encoded X.509 distinguished name. For a display version of the issuer, call SecCertificateCopyValues. The caller must CFRelease the value returned.

pub unsafe fn normalized_subject_content( self: &SecCertificate, error: *mut *mut CFError, ) -> Option<CFRetained<CFData>>

👎Deprecated: SecCertificateCopyNormalizedSubjectContent is deprecated. Use SecCertificateCopyNormalizedSubjectSequence instead.

Available on crate feature SecCertificate only.

Return the certificate’s normalized subject

Parameter certificate: The certificate from which to get values

Parameter error: An optional pointer to a CFErrorRef. This value is set if an error occurred. If not NULL the caller is responsible for releasing the CFErrorRef.

The subject is a sequence in the format used by SecItemCopyMatching. The content returned is a DER-encoded X.509 distinguished name. For a display version of the subject, call SecCertificateCopyValues. The caller must CFRelease the value returned.

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 SecCertificate

fn as_ref(&self) -> &AnyObject

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

impl AsRef<CFType> for SecCertificate

fn as_ref(&self) -> &CFType

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

impl AsRef<SecCertificate> for SecCertificate

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for SecCertificate

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for SecCertificate

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for SecCertificate

Available on crate feature SecCertificate only.

fn type_id() -> CFTypeID

Returns the type identifier of SecCertificate instances.

Returns: The CFTypeID of SecCertificate instances.

impl Debug for SecCertificate

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

Formats the value using the given formatter.

impl Deref for SecCertificate

type Target = CFType

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for SecCertificate

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 SecCertificate

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

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for SecCertificate

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 SecCertificate

const ENCODING_REF: Encoding

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

impl Type for SecCertificate

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 SecCertificate