[][src]Struct sgx_tcrypto::SgxEccHandle

pub struct SgxEccHandle { /* fields omitted */ }

ECC GF(p) context state.

This is a handle to the ECC GF(p) context state allocated and initialized used to perform elliptic curve cryptosystem standard functions. The algorithm stores the intermediate results of calculations performed using this context.

Methods

impl SgxEccHandle[src]

pub fn new() -> Self[src]

Constructs a new, empty SgxEccHandle.

pub fn open(&self) -> SgxError[src]

open returns an allocated and initialized context for the elliptic curve cryptosystem over a prime finite field, GF(p).

This context must be created prior to calling create_key_pair or compute_shared_dhkey. When the calling code has completed its set of ECC operations, close should be called to cleanup and deallocate the ECC context.

Description

open is utilized to allocate and initialize a 256-bit GF(p) cryptographic system. The caller does not allocate memory for the ECC state that this function returns. The state is specific to the implementation of the cryptography library and thus the allocation is performed by the library itself. If the ECC cryptographic function using this cryptographic system is completed or any error occurs, close should be called to free the state allocated by this algorithm.

Public key cryptography successfully allows to solving problems of information safety by enabling trusted communication over insecure channels. Although elliptic curves are well studied as a branch of mathematics, an interest to the cryptographic schemes based on elliptic curves is constantly rising due to the advantages that the elliptic curve algorithms provide in the wireless communications: shorter processing time and key length.

Elliptic curve cryptosystems (ECCs) implement a different way of creating public keys. As elliptic curve calculation is based on the addition of the rational points in the (x,y) plane and it is difficult to solve a discrete logarithm from these points, a higher level of safety is achieved through the cryptographic schemes that use the elliptic curves. The cryptographic systems that encrypt messages by using the properties of elliptic curves are hard to attack due to the extreme complexity of deciphering the private key.

Using of elliptic curves allows shorter public key length and encourages cryptographers to create cryptosystems with the same or higher encryption strength as the RSA or DSA cryptosystems. Because of the relatively short key length, ECCs do encryption and decryption faster on the hardware that requires less computation processing volumes.

Requirements

Library: libsgx_tcrypto.a

Errors

SGX_ERROR_INVALID_PARAMETER

The pointer is invalid.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The ECC context state was not initialized properly due to an internal cryptography library failure.

pub fn create_key_pair(
    &self
) -> SgxResult<(sgx_ec256_private_t, sgx_ec256_public_t)>
[src]

create_key_pair generates a private/public key pair on the ECC curve for the given cryptographic system.

open must be called to allocate and initialize the ECC context prior to making this call.

Description

This function populates private/public key pair. The calling code allocates memory for the private and public key pointers to be populated. The function generates a private key p_private and computes a public key p_public of the elliptic cryptosystem over a finite field GF(p).

The private key p_private is a number that lies in the range of [1, n-1] where n is the order of the elliptic curve base point. The public key p_public is an elliptic curve point such that p_public = p_private *G, where G is the base point of the elliptic curve. The context of the point p_public as an elliptic curve point must be created by using the function open.

Requirements

Library: libsgx_tcrypto.a

Return value

sgx_ec256_private_t

The private key which is a number that lies in the range of [1, n-1] where n is the order of the elliptic curve base point.

sgx_ec256_public_t

The public key which is an elliptic curve point such that:

public key = private key * G, where G is the base point of the elliptic curve.

Errors

SGX_ERROR_INVALID_PARAMETER

The pointer is invalid.

SGX_ERROR_INVALID_STATE

The ECC state is not initialized.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The key creation process failed due to an internal cryptography library failure.

pub fn create_align_key_pair(
    &self
) -> SgxResult<(sgx_align_ec256_private_t, sgx_ec256_public_t)>
[src]

pub fn check_point(&self, point: &sgx_ec256_public_t) -> SgxResult<bool>[src]

check_point checks whether the input point is a valid point on the ECC curve for the given cryptographic system.

open context must be called to allocate and initialize the ECC context prior to making this call.

Description

check_point validates whether the input point is a valid point on the ECC curve for the given cryptographic system.

Parameters

point

A pointer to the point to perform validity check on.

Requirements

Library: libsgx_tcrypto.a

Return value

true

The input point is valid

false

The input point is not valid

Errors

SGX_ERROR_INVALID_PARAMETER

The pointer is invalid.

SGX_ERROR_INVALID_STATE

The ECC state is not initialized.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An internal cryptography library failure occurred.

pub fn compute_shared_dhkey(
    &self,
    private_b: &sgx_ec256_private_t,
    public_ga: &sgx_ec256_public_t
) -> SgxResult<sgx_ec256_dh_shared_t>
[src]

compute_shared_dhkey generates a secret key shared between two participants of the cryptosystem.

Description

This function computes the Diffie-Hellman shared key based on the enclave’s own (local) private key and remote enclave’s public Ga Key.

The function computes a secret number sharedKey, which is a secret key shared between two participants of the cryptosystem.

In cryptography, metasyntactic names such as Alice as Bob are normally used as examples and in discussions and stand for participant A and participant B.

Both participants (Alice and Bob) use the cryptosystem for receiving a common secret point on the elliptic curve called a secret key (sharedKey). To receive a secret key, participants apply the Diffie-Hellman key-agreement scheme involving public key exchange. The value of the secret key entirely depends on participants.

According to the scheme, Alice and Bob perform the following operations:

  1. Alice calculates her own public key pubKeyA by using her private key privKeyA: pubKeyA = privKeyA * G, where G is the base point of the elliptic curve.

  2. Alice passes the public key to Bob.

  3. Bob calculates his own public key pubKeyB by using his private key privKeyB: pubKeyB = privKeyB * G, where G is a base point of the elliptic curve.

  4. Bob passes the public key to Alice.

  5. Alice gets Bob's public key and calculates the secret point shareKeyA. When calculating, she uses her own private key and Bob's public key and applies the following formula:

shareKeyA = privKeyA * pubKeyB = privKeyA * privKeyB * G.

  1. Bob gets Alice's public key and calculates the secret point shareKeyB. When calculating, he uses his own private key and Alice's public key and applies the following formula:

shareKeyB = privKeyB * pubKeyA = privKeyB * privKeyA * G.

As the following equation is true privKeyA * privKeyB * G = privKeyB * privKeyA * G, the result of both calculations is the same, that is, the equation shareKeyA = shareKeyB is true. The secret point serves as a secret key.

Shared secret shareKey is an x-coordinate of the secret point on the elliptic curve. The elliptic curve domain parameters must be hitherto defined by the function: open.

Parameters

private_b

A pointer to the local private key.

public_ga

A pointer to the remote public key.

Requirements

Library: libsgx_tcrypto.a

Return value

The secret key generated by this function which is a common point on the elliptic curve.

Errors

SGX_ERROR_INVALID_PARAMETER

The pointer is invalid.

SGX_ERROR_INVALID_STATE

The ECC state is not initialized.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The key creation process failed due to an internal cryptography library failure.

pub fn compute_align_shared_dhkey(
    &self,
    private_b: &sgx_ec256_private_t,
    public_ga: &sgx_ec256_public_t
) -> SgxResult<sgx_align_ec256_dh_shared_t>
[src]

pub fn ecdsa_sign_msg<T>(
    &self,
    data: &T,
    private: &sgx_ec256_private_t
) -> SgxResult<sgx_ec256_signature_t> where
    T: Copy + ContiguousMemory
[src]

ecdsa_sign_msg computes a digital signature with a given private key over an input dataset.

Description

This function computes a digital signature over the input dataset based on the put private key.

A message digest is a fixed size number derived from the original message in this case)

The signer's private key and the message digest are used to create a signature.

A digital signature over a message consists of a pair of large numbers, 256-bits each, which the given function computes.

The scheme used for computing a digital signature is of the ECDSA scheme, an elliptic curve of the DSA scheme.

The keys can be generated and set up by the function: create_key_pair.

The elliptic curve domain parameters must be created by function: open.

Parameters

data

A pointer to the data to calculate the signature over.

private

A pointer to the private key to be used in the calculation of the signature.

Requirements

Library: libsgx_tcrypto.a

Return value

The signature generated by this function.

Errors

SGX_ERROR_INVALID_PARAMETER

The pointer is invalid.

SGX_ERROR_INVALID_STATE

The ECC state is not initialized.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The signature generation process failed due to an internal cryptography library failure.

pub fn ecdsa_sign_slice<T>(
    &self,
    data: &[T],
    private: &sgx_ec256_private_t
) -> SgxResult<sgx_ec256_signature_t> where
    T: Copy + ContiguousMemory
[src]

ecdsa_sign_slice computes a digital signature with a given private key over an input dataset.

pub fn ecdsa_verify_msg<T>(
    &self,
    data: &T,
    public: &sgx_ec256_public_t,
    signature: &sgx_ec256_signature_t
) -> SgxResult<bool> where
    T: Copy + ContiguousMemory
[src]

ecdsa_verify_msg verifies the input digital signature with a given public key over an input dataset.

Description

This function verifies the signature for the given data set based on the input public key.

A digital signature over a message consists of a pair of large numbers, 256-bits each, which could be created by function: sgx_ecdsa_sign. The scheme used for computing a digital signature is of the ECDSA scheme, an elliptic curve of the DSA scheme.

The elliptic curve domain parameters must be created by function: open.

Parameters

data

A pointer to the signed dataset to verify.

public

A pointer to the public key to be used in the calculation of the signature.

signature

A pointer to the signature to be verified.

Requirements

Library: libsgx_tcrypto.a

Return value

true

Digital signature is valid.

false

Digital signature is not valid.

Errors

SGX_ERROR_INVALID_PARAMETER

The pointer is invalid.

SGX_ERROR_INVALID_STATE

The ECC state is not initialized.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The verification process failed due to an internal cryptography library failure.

pub fn ecdsa_verify_slice<T>(
    &self,
    data: &[T],
    public: &sgx_ec256_public_t,
    signature: &sgx_ec256_signature_t
) -> SgxResult<bool> where
    T: Copy + ContiguousMemory
[src]

ecdsa_verify_slice verifies the input digital signature with a given public key over an input dataset.

pub fn ecdsa_verify_hash(
    &self,
    hash: &sgx_sha256_hash_t,
    public: &sgx_ec256_public_t,
    signature: &sgx_ec256_signature_t
) -> SgxResult<bool>
[src]

pub fn close(&self) -> SgxError[src]

close cleans up and deallocates the ECC 256 GF(p) state that was allocated in function open.

Description

close is used by calling code to deallocate memory used for storing the ECC 256 GF(p) state used in ECC cryptographic calculations.

Requirements

Library: libsgx_tcrypto.a

Errors

SGX_ERROR_INVALID_PARAMETER

The input handle is invalid.

Trait Implementations

impl Default for SgxEccHandle[src]

impl Drop for SgxEccHandle[src]

fn drop(&mut self)[src]

close cleans up and deallocates the ECC 256 GF(p) state that was allocated in function open.

Auto Trait Implementations

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.