Next: , Previous: Working with keys, Up: AC Interface

6.6.6 Using cryptographic functions

The following flags might be relevant:

GCRY_AC_FLAG_NO_BLINDING
Disable any blinding, which might be supported by the chosen algorithm; blinding is the default.

There exist two kinds of cryptographic functions available through the ac interface: primitives, and high-level functions.

Primitives deal with MPIs (data sets) directly; what they provide is direct access to the cryptographic operations provided by an algorithm implementation.

High-level functions deal with octet strings, according to a specified “scheme”. Schemes make use of “encoding methods”, which are responsible for converting the provided octet strings into MPIs, which are then forwared to the cryptographic primitives. Since schemes are to be used for a special purpose in order to achieve a particular security goal, there exist “encryption schemes” and “signature schemes”. Encoding methods can be used seperately or implicitly through schemes.

What follows is a description of the cryptographic primitives.

— Function: gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t handle, unsigned int flags, gcry_ac_key_t key, gcry_mpi_t data_plain, gcry_ac_data_t *data_encrypted)

Encrypts the plain text MPI value data_plain with the key public key under the control of the flags flags and stores the resulting data set into data_encrypted.

— Function: gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t handle, unsigned int flags, gcry_ac_key_t key, gcry_mpi_t *data_plain, gcry_ac_data_t data_encrypted)

Decrypts the encrypted data contained in the data set data_encrypted with the secret key KEY under the control of the flags flags and stores the resulting plain text MPI value in DATA_PLAIN.

— Function: gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t handle, gcry_ac_key_t key, gcry_mpi_t data, gcry_ac_data_t *data_signature)

Signs the data contained in data with the secret key key and stores the resulting signature in the data set data_signature.

— Function: gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t handle, gcry_ac_key_t key, gcry_mpi_t data, gcry_ac_data_t data_signature)

Verifies that the signature contained in the data set data_signature is indeed the result of signing the data contained in data with the secret key belonging to the public key key.

What follows is a description of the high-level functions.

The type “gcry_ac_em_t” is used for specifying encoding methods; the following methods are supported:

GCRY_AC_EME_PKCS_V1_5
PKCS-V1_5 Encoding Method for Encryption. Options must be provided through a pointer to a correctly initialized object of type gcry_ac_eme_pkcs_v1_5_t.
GCRY_AC_EMSA_PKCS_V1_5
PKCS-V1_5 Encoding Method for Signatures with Appendix. Options must be provided through a pointer to a correctly initialized object of type gcry_ac_emsa_pkcs_v1_5_t.

Option structure types:

gcry_ac_eme_pkcs_v1_5_t
gcry_ac_key_t key
gcry_ac_handle_t handle

gcry_ac_emsa_pkcs_v1_5_t
gcry_md_algo_t md
size_t em_n

Encoding methods can be used directly through the following functions:

— Function: gcry_error_t gcry_ac_data_encode (gcry_ac_em_t method, unsigned int flags, void *options, unsigned char *m, size_t m_n, unsigned char **em, size_t *em_n)

Encodes the message contained in m of size m_n according to method, flags and options. The newly created encoded message is stored in em and em_n.

— Function: gcry_error_t gcry_ac_data_decode (gcry_ac_em_t method, unsigned int flags, void *options, unsigned char *em, size_t em_n, unsigned char **m, size_t *m_n)

Decodes the message contained in em of size em_n according to method, flags and options. The newly created decoded message is stored in m and m_n.

The type “gcry_ac_scheme_t” is used for specifying schemes; the following schemes are supported:

GCRY_AC_ES_PKCS_V1_5
PKCS-V1_5 Encryption Scheme. No options can be provided.
GCRY_AC_SSA_PKCS_V1_5
PKCS-V1_5 Signature Scheme (with Appendix). Options can be provided through a pointer to a correctly initialized object of type gcry_ac_ssa_pkcs_v1_5_t.

Option structure types:

gcry_ac_ssa_pkcs_v1_5_t
gcry_md_algo_t md

The functions implementing schemes:

— Function: gcry_error_t gcry_ac_data_encrypt_scheme (gcry_ac_handle_t handle, gcry_ac_scheme_t scheme, unsigned int flags, void *opts, gcry_ac_key_t key, gcry_ac_io_t *io_message, gcry_ac_io_t *io_cipher)

Encrypts the plain text readable from io_message through handle with the public key key according to scheme, flags and opts. If opts is not NULL, it has to be a pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t). The encrypted message is written to io_cipher.

— Function: gcry_error_t gcry_ac_data_decrypt_scheme (gcry_ac_handle_t handle, gcry_ac_scheme_t scheme, unsigned int flags, void *opts, gcry_ac_key_t key, gcry_ac_io_t *io_cipher, gcry_ac_io_t *io_message)

Decrypts the cipher text readable from io_cipher through handle with the secret key key according to scheme, flags and opts. If opts is not NULL, it has to be a pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t). The decrypted message is written to io_message.

— Function: gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t handle, gcry_ac_scheme_t scheme, unsigned int flags, void *opts, gcry_ac_key_t key, gcry_ac_io_t *io_message, gcry_ac_io_t *io_signature)

Signs the message readable from io_message through handle with the secret key key according to scheme, flags and opts. If opts is not NULL, it has to be a pointer to a structure specific to the chosen scheme (gcry_ac_ssa_*_t). The signature is written to io_signature.

— Function: gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t handle, gcry_ac_scheme_t scheme, unsigned int flags, void *opts, gcry_ac_key_t key, gcry_ac_io_t *io_message, gcry_ac_io_t *io_signature)

Verifies through handle that the signature readable from io_signature is indeed the result of signing the message readable from io_message with the secret key belonging to the public key key according to scheme and opts. If opts is not NULL, it has to be an anonymous structure (gcry_ac_ssa_*_t) specific to the chosen scheme.