Struct SecTrust

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

Available on crate feature SecTrust only.

CFType used for performing X.509 certificate trust evaluations.

See also Apple’s documentation

Implementations

impl SecTrust

pub unsafe fn create_with_certificates( certificates: &CFType, policies: Option<&CFType>, trust: NonNull<*mut SecTrust>, ) -> i32

Creates a trust object based on the given certificates and policies.

Parameter certificates: The group of certificates to verify. This can either be a CFArrayRef of SecCertificateRef objects or a single SecCertificateRef

Parameter policies: An array of one or more policies. You may pass a SecPolicyRef to represent a single policy.

Parameter trust: On return, a pointer to the trust management reference.

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

If multiple policies are passed in, all policies must verify for the chain to be considered valid.

pub unsafe fn set_policies(self: &SecTrust, policies: &CFType) -> i32

Set the policies for which trust should be verified.

Parameter trust: A trust reference.

Parameter policies: An array of one or more policies. You may pass a SecPolicyRef to represent a single policy.

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

This function will invalidate the existing trust result, requiring a fresh evaluation for the newly-set policies.

pub unsafe fn copy_policies( self: &SecTrust, policies: NonNull<*const CFArray>, ) -> i32

Returns an array of policies used for this evaluation.

Parameter trust: A reference to a trust object.

Parameter policies: On return, an array of policies used by this trust. Call the CFRelease function to release this reference.

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

pub unsafe fn set_network_fetch_allowed( self: &SecTrust, allow_fetch: bool, ) -> i32

Specifies whether a trust evaluation is permitted to fetch missing intermediate certificates from the network.

Parameter trust: A trust reference.

Parameter allowFetch: If true, and a certificate’s issuer is not present in the trust reference but its network location is known, the evaluation is permitted to attempt to download it automatically. Pass false to disable network fetch for this trust evaluation.

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

By default, network fetch of missing certificates is enabled if the trust evaluation includes the SSL policy, otherwise it is disabled.

pub unsafe fn network_fetch_allowed( self: &SecTrust, allow_fetch: NonNull<u8>, ) -> i32

Returns whether a trust evaluation is permitted to fetch missing intermediate certificates from the network.

Parameter trust: A trust reference.

Parameter allowFetch: On return, the boolean pointed to by this parameter is set to true if the evaluation is permitted to download missing certificates.

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

By default, network fetch of missing certificates is enabled if the trust evaluation includes the SSL policy, otherwise it is disabled.

pub unsafe fn set_anchor_certificates( self: &SecTrust, anchor_certificates: Option<&CFArray>, ) -> i32

Sets the anchor certificates for a given trust.

Parameter trust: A reference to a trust object.

Parameter anchorCertificates: An array of anchor certificates. Pass NULL to restore the default set of anchor certificates.

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

Calling this function without also calling SecTrustSetAnchorCertificatesOnly() will disable trusting any anchors other than the ones in anchorCertificates.

pub unsafe fn set_anchor_certificates_only( self: &SecTrust, anchor_certificates_only: bool, ) -> i32

Reenables trusting anchor certificates in addition to those passed in via the SecTrustSetAnchorCertificates API.

Parameter trust: A reference to a trust object.

Parameter anchorCertificatesOnly: If true, disables trusting any anchors other than the ones passed in via SecTrustSetAnchorCertificates(). If false, the built in anchor certificates are also trusted.

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

pub unsafe fn copy_custom_anchor_certificates( self: &SecTrust, anchors: NonNull<*const CFArray>, ) -> i32

Returns an array of custom anchor certificates used by a given trust, as set by a prior call to SecTrustSetAnchorCertificates, or NULL if no custom anchors have been specified.

Parameter trust: A reference to a trust object.

Parameter anchors: On return, an array of custom anchor certificates (roots) used by this trust, or NULL if no custom anchors have been specified. Call the CFRelease function to release this reference.

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

pub unsafe fn set_verify_date(self: &SecTrust, verify_date: &CFDate) -> i32

Set the date for which the trust should be verified.

Parameter trust: A reference to a trust object.

Parameter verifyDate: The date for which to verify trust.

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

This function lets you evaluate certificate validity for a given date (for example, to determine if a signature was valid on the date it was signed, even if the certificate has since expired.) If this function is not called, the time at which SecTrustEvaluate() is called is used implicitly as the verification time.

pub unsafe fn verify_time(self: &SecTrust) -> CFAbsoluteTime

Returns the verify time.

Parameter trust: A reference to the trust object being verified.

Returns: A CFAbsoluteTime value representing the time at which certificates should be checked for validity.

This function retrieves the verification time for the given trust reference, as set by a prior call to SecTrustSetVerifyDate(). If the verification time has not been set, this function returns a value of 0, indicating that the current date/time is implicitly used for verification.

pub unsafe fn evaluate( self: &SecTrust, result: NonNull<SecTrustResultType>, ) -> i32

👎Deprecated

Evaluates a trust reference synchronously.

Parameter trust: A reference to the trust object to evaluate.

Parameter result: A pointer to a result type.

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

This function will completely evaluate trust before returning, possibly including network access to fetch intermediate certificates or to perform revocation checking. Since this function can block during those operations, you should call it from within a function that is placed on a dispatch queue, or in a separate thread from your application’s main run loop. Alternatively, you can use the SecTrustEvaluateAsync function.

pub unsafe fn evaluate_with_error( self: &SecTrust, error: *mut *mut CFError, ) -> bool

Evaluates a trust reference synchronously.

Parameter trust: A reference to the trust object to evaluate.

Parameter error: A pointer to an error object

Returns: A boolean value indicating whether the certificate is trusted

This function will completely evaluate trust before returning, possibly including network access to fetch intermediate certificates or to perform revocation checking. Since this function can block during those operations, you should call it from within a function that is placed on a dispatch queue, or in a separate thread from your application’s main run loop. If the certificate is trusted and the result is true, the error will be set to NULL. If the certificate is not trusted or the evaluation was unable to complete, the result will be false and the error will be set with a description of the failure. The error contains a code for the most serious error encountered (if multiple trust failures occurred). The localized description indicates the certificate with the most serious problem and the type of error. The underlying error contains a localized description of each certificate in the chain that had an error and all errors found with that certificate.

impl SecTrust

pub unsafe fn trust_result( self: &SecTrust, result: NonNull<SecTrustResultType>, ) -> i32

Parameter trust: A reference to a trust object.

Parameter result: A pointer to the result from the most recent call to SecTrustEvaluate for this trust reference. If SecTrustEvaluate has not been called or trust parameters have changed, the result is kSecTrustResultInvalid.

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

This function replaces SecTrustGetResult for the purpose of obtaining the current evaluation result of a given trust reference.

pub unsafe fn public_key(self: &SecTrust) -> Option<CFRetained<SecKey>>

👎Deprecated

Available on crate feature SecBase only.

Return the public key for a leaf certificate after it has been evaluated.

Parameter trust: A reference to the trust object which has been evaluated.

Returns: The certificate’s public key, or NULL if it the public key could not be extracted (this can happen if the public key algorithm is not supported). The caller is responsible for calling CFRelease on the returned key when it is no longer needed.

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

Available on crate feature SecBase only.

Return the public key for a leaf certificate after it has been evaluated.

Parameter trust: A reference to the trust object which has been evaluated.

Returns: The certificate’s public key, or NULL if it the public key could not be extracted (this can happen if the public key algorithm is not supported). The caller is responsible for calling CFRelease on the returned key when it is no longer needed.

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

pub unsafe fn certificate_count(self: &SecTrust) -> CFIndex

Returns the number of certificates in an evaluated certificate chain.

Parameter trust: A reference to a trust object.

Returns: The number of certificates in the trust chain, including the anchor.

Important: if the trust reference has not yet been evaluated, this function will evaluate it first before returning. If speed is critical, you may want to call SecTrustGetTrustResult first to make sure that a result other than kSecTrustResultInvalid is present for the trust object.

pub unsafe fn certificate_at_index( self: &SecTrust, ix: CFIndex, ) -> Option<CFRetained<SecCertificate>>

👎Deprecated

Available on crate feature SecBase only.

Returns a certificate from the trust chain.

Parameter trust: Reference to a trust object.

Parameter ix: The index of the requested certificate. Indices run from 0 (leaf) to the anchor (or last certificate found if no anchor was found). The leaf cert (index 0) is always present regardless of whether the trust reference has been evaluated or not.

Returns: A SecCertificateRef for the requested certificate.

This API is fundamentally not thread-safe – other threads using the same trust object may trigger trust evaluations that release the returned certificate or change the certificate chain as a thread is iterating through the certificate chain. The replacement function SecTrustCopyCertificateChain provides thread-safe results.

pub unsafe fn exceptions(self: &SecTrust) -> Option<CFRetained<CFData>>

Returns an opaque cookie which will allow future evaluations of the current certificate to succeed.

Parameter trust: A reference to an evaluated trust object.

Returns: An opaque cookie which when passed to SecTrustSetExceptions() will cause a call to SecTrustEvaluate() return kSecTrustResultProceed. This will happen upon subsequent evaluation of the current certificate unless some new error starts happening that wasn’t being reported when the cookie was returned from this function (for example, if the certificate expires then evaluation will start failing again until a new cookie is obtained.)

Normally this API should only be called once the errors have been presented to the user and the user decided to trust the current certificate chain regardless of the errors being presented, for the current application/server/protocol combination.

pub unsafe fn set_exceptions( self: &SecTrust, exceptions: Option<&CFData>, ) -> bool

Set a trust cookie to be used for evaluating this certificate chain.

Parameter trust: A reference to a trust object.

Parameter exceptions: An exceptions cookie as returned by a call to SecTrustCopyExceptions() in the past. You may pass NULL to clear any exceptions which have been previously set on this trust reference.

Returns: Upon calling SecTrustEvaluate(), any failures that were present at the time the exceptions object was created are ignored, and instead of returning kSecTrustResultRecoverableTrustFailure, kSecTrustResultProceed will be returned (if the certificate for which exceptions was created matches the current leaf certificate).

Returns: Returns true if the exceptions cookies was valid and matches the current leaf certificate, false otherwise. This function will invalidate the existing trust result, requiring a subsequent evaluation for the newly-set exceptions. Note that this function returning true doesn’t mean the caller can skip calling SecTrustEvaluate, as there may be new errors since the exceptions cookie was created (for example, a certificate may have subsequently expired.)

Clients of this interface will need to establish the context of this exception to later decide when this exception cookie is to be used. Examples of this context would be the server we are connecting to, the ssid of the wireless network for which this cert is needed, the account for which this cert should be considered valid, and so on.

pub unsafe fn properties(self: &SecTrust) -> Option<CFRetained<CFArray>>

👎Deprecated

Return a property array for this trust evaluation.

Parameter trust: A reference to a trust object. If the trust has not been evaluated, the returned property array will be empty.

Returns: A property array. It is the caller’s responsibility to CFRelease the returned array when it is no longer needed.

On macOS, this function returns an ordered array of CFDictionaryRef instances for each certificate in the chain. Indices run from 0 (leaf) to the anchor (or last certificate found if no anchor was found.) On other platforms, this function returns an unordered array of CFDictionary instances. See the “Trust Property Constants” section for a list of currently defined keys. The error information conveyed via this interface is also conveyed via the returned error of SecTrustEvaluateWithError.

pub unsafe fn result(self: &SecTrust) -> Option<CFRetained<CFDictionary>>

Returns a dictionary containing information about the evaluated certificate chain for use by clients.

Parameter trust: A reference to a trust object.

Returns: A dictionary with various fields that can be displayed to the user, or NULL if no additional info is available or the trust has not yet been validated. The caller is responsible for calling CFRelease on the value returned when it is no longer needed.

Returns a dictionary for the overall trust evaluation. See the “Trust Result Constants” section for a list of currently defined keys.

pub unsafe fn set_ocsp_response( self: &SecTrust, response_data: Option<&CFType>, ) -> i32

Attach OCSPResponse data to a trust object.

Parameter trust: A reference to a trust object.

Parameter responseData: This may be either a CFData object containing a single DER-encoded OCSPResponse (per RFC 2560), or a CFArray of these.

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

Allows the caller to provide OCSPResponse data (which may be obtained during a TLS/SSL handshake, per RFC 3546) as input to a trust evaluation. If this data is available, it can obviate the need to contact an OCSP server for current revocation information.

pub unsafe fn set_signed_certificate_timestamps( self: &SecTrust, sct_array: Option<&CFArray>, ) -> i32

Attach SignedCertificateTimestamp data to a trust object.

Parameter trust: A reference to a trust object.

Parameter sctArray: is a CFArray of CFData objects each containing a SCT (per RFC 6962).

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

Allows the caller to provide SCT data (which may be obtained during a TLS/SSL handshake, per RFC 6962) as input to a trust evaluation.

pub unsafe fn certificate_chain(self: &SecTrust) -> Option<CFRetained<CFArray>>

Returns the certificate trust chain

Parameter trust: Reference to a trust object.

Returns: A CFArray of the SecCertificateRefs for the resulting certificate chain

impl SecTrust

pub unsafe fn set_options(self: &SecTrust, options: SecTrustOptionFlags) -> i32

Sets optional flags for customizing a trust evaluation.

Parameter trustRef: A trust reference.

Parameter options: Flags to change evaluation behavior for this trust.

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

This function is not available on iOS. Use SecTrustSetExceptions and SecTrustCopyExceptions to modify default trust results, and SecTrustSetNetworkFetchAllowed to specify whether missing CA certificates can be fetched from the network.

pub unsafe fn set_parameters( self: &SecTrust, action: CSSM_TP_ACTION, action_data: &CFData, ) -> i32

👎Deprecated

Available on crate features cssmconfig and cssmtype only.

Sets the action and action data for a trust object.

Parameter trustRef: The reference to the trust to change.

Parameter action: A trust action.

Parameter actionData: A reference to data associated with this action.

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

This function is deprecated in OS X 10.7 and later, where it was replaced by SecTrustSetOptions, and is not available on iOS. Your code should use SecTrustSetExceptions and SecTrustCopyExceptions to modify default trust results, and SecTrustSetNetworkFetchAllowed to specify whether missing CA certificates can be fetched from the network.

pub unsafe fn set_keychains( self: &SecTrust, keychain_or_array: Option<&CFType>, ) -> i32

👎Deprecated

Sets the keychains for a given trust object.

Parameter trust: A reference to a trust object.

Parameter keychainOrArray: A reference to an array of keychains to search, a single keychain, or NULL to use the default keychain search list.

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

This function is deprecated in macOS 10.13 and later. Beginning in macOS 10.12, this function no longer affected the behavior of the trust evaluation: the user’s keychain search list and the system anchors keychain are searched for certificates to complete the chain. To change the keychains that are searched, callers must use SecKeychainSetSearchList to change the user’s keychain search list. Note: this function was never applicable to iOS.

pub unsafe fn get_trust( self: &SecTrust, result: *mut SecTrustResultType, cert_chain: *mut *const CFArray, status_chain: *mut *mut CSSM_TP_APPLE_EVIDENCE_INFO, ) -> i32

👎Deprecated

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

Returns detailed information on the outcome of an evaluation.

Parameter trustRef: A reference to a trust object.

Parameter result: A pointer to the result from the call to SecTrustEvaluate.

Parameter certChain: On return, a pointer to the certificate chain used to validate the input certificate. Call the CFRelease function to release this pointer.

Parameter statusChain: On return, a pointer to the status of the certificate chain. Do not attempt to free this pointer; it remains valid until the trust is destroyed or the next call to SecTrustEvaluate.

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

This function is deprecated in OS X 10.7 and later, and is not available on iOS. To get the complete certificate chain, use SecTrustCopyCertificateChain. To get detailed status information for each certificate, use SecTrustCopyProperties. To get the overall trust result for the evaluation, use SecTrustGetTrustResult.

pub unsafe fn cssm_result( self: &SecTrust, result: NonNull<CSSM_TP_VERIFY_CONTEXT_RESULT_PTR>, ) -> i32

👎Deprecated

Available on crate features cssmconfig and cssmtype only.

Gets the CSSM trust result.

Parameter trust: A reference to a trust.

Parameter result: On return, a pointer to the CSSM trust result.

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

This function is deprecated in OS X 10.7 and later, and is not available on iOS. To get detailed status information for each certificate, use SecTrustCopyProperties. To get the overall trust result for the evaluation, use SecTrustGetTrustResult.

pub unsafe fn cssm_result_code( self: &SecTrust, result_code: NonNull<i32>, ) -> i32

👎Deprecated

Gets the result code from the most recent call to SecTrustEvaluate for the specified trust.

Parameter trust: A reference to a trust.

Parameter resultCode: On return, the result code produced by the most recent evaluation of the given trust (cssmerr.h). The value of resultCode is undefined if SecTrustEvaluate has not been called.

Returns: A result code. See “Security Error Codes” (SecBase.h). Returns errSecTrustNotAvailable if SecTrustEvaluate has not been called for the specified trust.

This function is deprecated in OS X 10.7 and later, and is not available on iOS. To get detailed status information for each certificate, use SecTrustCopyProperties. To get the overall trust result for the evaluation, use SecTrustGetTrustResult.

pub unsafe fn tp_handle(self: &SecTrust, handle: NonNull<CSSM_TP_HANDLE>) -> i32

👎Deprecated

Available on crate features cssmconfig and cssmtype only.

Gets the CSSM trust handle

Parameter trust: A reference to a trust.

Parameter handle: On return, a CSSM trust handle.

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

This function is deprecated in OS X 10.7 and later.

pub unsafe fn copy_anchor_certificates(anchors: NonNull<*const CFArray>) -> i32

Returns an array of default anchor (root) certificates used by the system.

Parameter anchors: On return, an array containing the system’s default anchors (roots). Call the CFRelease function to release this pointer.

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

This function is not available on iOS, as certificate data for system-trusted roots is currently unavailable on that platform.

impl SecTrust

pub unsafe fn settings_copy_trust_settings( cert_ref: &SecCertificate, domain: SecTrustSettingsDomain, trust_settings: NonNull<*const CFArray>, ) -> i32

Available on crate features SecTrustSettings and SecBase only.

pub unsafe fn settings_set_trust_settings( cert_ref: &SecCertificate, domain: SecTrustSettingsDomain, trust_settings_dict_or_array: Option<&CFType>, ) -> i32

Available on crate features SecTrustSettings and SecBase only.

pub unsafe fn settings_remove_trust_settings( cert_ref: &SecCertificate, domain: SecTrustSettingsDomain, ) -> i32

Available on crate features SecTrustSettings and SecBase only.

pub unsafe fn settings_copy_certificates( domain: SecTrustSettingsDomain, cert_array: *mut *const CFArray, ) -> i32

Available on crate feature SecTrustSettings only.

pub unsafe fn settings_copy_modification_date( cert_ref: &SecCertificate, domain: SecTrustSettingsDomain, modification_date: NonNull<*const CFDate>, ) -> i32

Available on crate features SecTrustSettings and SecBase only.

pub unsafe fn settings_create_external_representation( domain: SecTrustSettingsDomain, trust_settings: NonNull<*const CFData>, ) -> i32

Available on crate feature SecTrustSettings only.

pub unsafe fn settings_import_external_representation( domain: SecTrustSettingsDomain, trust_settings: &CFData, ) -> i32

Available on crate feature SecTrustSettings only.

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 SecTrust

fn as_ref(&self) -> &AnyObject

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

impl AsRef<CFType> for SecTrust

fn as_ref(&self) -> &CFType

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

impl AsRef<SecTrust> for SecTrust

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for SecTrust

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for SecTrust

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for SecTrust

fn type_id() -> CFTypeID

Returns the type identifier of SecTrust instances.

Returns: The CFTypeID of SecTrust instances.

impl Debug for SecTrust

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

Formats the value using the given formatter.

impl Deref for SecTrust

type Target = CFType

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for SecTrust

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 SecTrust

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

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for SecTrust

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 SecTrust

const ENCODING_REF: Encoding

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

impl Type for SecTrust

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 SecTrust