gnutls.info: Managing encrypted keys

More on certificate authentication

certtool Invocation

OCSP stapling

Back to Software Index

4.2.5 Managing encrypted keys
-----------------------------

Transferring or storing private keys in plain may not be a good idea,
since any compromise is irreparable.  Storing the keys in hardware
security modules (see Note: Smart cards and HSMs) could solve the
storage problem but it is not always practical or efficient enough.
This section describes ways to store and transfer encrypted private
keys.

There are methods for key encryption, namely the PKCS #8, PKCS #12 and
OpenSSL's custom encrypted private key formats.  The PKCS #8 and the
OpenSSL's method allow encryption of the private key, while the PKCS #12
method allows, in addition, the bundling of accompanying data into the
structure.  That is typically the corresponding certificate, as well as
a trusted CA certificate.

High level functionality
........................

Generic and higher level private key import functions are available,
that import plain or encrypted keys and will auto-detect the encrypted
key format.

 -- Function: int gnutls_privkey_import_x509_raw (gnutls_privkey_t PKEY,
          const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT,
          const char * PASSWORD, unsigned int FLAGS)
     PKEY: The private key

     DATA: The private key data to be imported

     FORMAT: The format of the private key

     PASSWORD: A password (optional)

     FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t

     This function will import the given private key to the abstract
     'gnutls_privkey_t' type.

     The supported formats are basic unencrypted key, PKCS8, PKCS12, and
     the openssl format.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.1.0

 -- Function: int gnutls_x509_privkey_import2 (gnutls_x509_privkey_t
          KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t
          FORMAT, const char * PASSWORD, unsigned int FLAGS)
     KEY: The data to store the parsed key

     DATA: The DER or PEM encoded key.

     FORMAT: One of DER or PEM

     PASSWORD: A password (optional)

     FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t

     This function will import the given DER or PEM encoded key, to the
     native 'gnutls_x509_privkey_t' format, irrespective of the input
     format.  The input format is auto-detected.

     The supported formats are basic unencrypted key, PKCS8, PKCS12, and
     the openssl format.

     If the provided key is encrypted but no password was given, then
     'GNUTLS_E_DECRYPTION_FAILED' is returned.  Since GnuTLS 3.4.0 this
     function will utilize the PIN callbacks if any.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

Any keys imported using those functions can be imported to a certificate
credentials structure using Note: gnutls_certificate_set_key, or
alternatively they can be directly imported using Note:
gnutls_certificate_set_x509_key_file2.

PKCS #8 structures
..................

PKCS #8 keys can be imported and exported as normal private keys using
the functions below.  An addition to the normal import functions, are a
password and a flags argument.  The flags can be any element of the
'gnutls_pkcs_encrypt_flags_t' enumeration.  Note however, that GnuTLS
only supports the PKCS #5 PBES2 encryption scheme.  Keys encrypted with
the obsolete PBES1 scheme cannot be decrypted.

'INT Note: gnutls_x509_privkey_import_pkcs8 (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS)'
'INT Note: gnutls_x509_privkey_export_pkcs8 (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)'
'INT Note: gnutls_x509_privkey_export2_pkcs8 (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS, gnutls_datum_t * OUT)'

'GNUTLS_PKCS_PLAIN'
     Unencrypted private key.
'GNUTLS_PKCS_PKCS12_3DES'
     PKCS-12 3DES.
'GNUTLS_PKCS_PKCS12_ARCFOUR'
     PKCS-12 ARCFOUR.
'GNUTLS_PKCS_PKCS12_RC2_40'
     PKCS-12 RC2-40.
'GNUTLS_PKCS_PBES2_3DES'
     PBES2 3DES.
'GNUTLS_PKCS_PBES2_AES_128'
     PBES2 AES-128.
'GNUTLS_PKCS_PBES2_AES_192'
     PBES2 AES-192.
'GNUTLS_PKCS_PBES2_AES_256'
     PBES2 AES-256.
'GNUTLS_PKCS_NULL_PASSWORD'
     Some schemas distinguish between an empty and a NULL password.
'GNUTLS_PKCS_PBES2_DES'
     PBES2 single DES.
'GNUTLS_PKCS_PBES1_DES_MD5'
     PBES1 with single DES; for compatibility with openssl only.
'GNUTLS_PKCS_PBES2_GOST_TC26Z'
     PBES2 GOST 28147-89 CFB with TC26-Z S-box.
'GNUTLS_PKCS_PBES2_GOST_CPA'
     PBES2 GOST 28147-89 CFB with CryptoPro-A S-box.
'GNUTLS_PKCS_PBES2_GOST_CPB'
     PBES2 GOST 28147-89 CFB with CryptoPro-B S-box.
'GNUTLS_PKCS_PBES2_GOST_CPC'
     PBES2 GOST 28147-89 CFB with CryptoPro-C S-box.
'GNUTLS_PKCS_PBES2_GOST_CPD'
     PBES2 GOST 28147-89 CFB with CryptoPro-D S-box.

Figure 4.5: Encryption flags

PKCS #12 structures
...................

A PKCS #12 structure [Note: PKCS12] usually contains a user's private
keys and certificates.  It is commonly used in browsers to export and
import the user's identities.  A file containing such a key can be
directly imported to a certificate credentials structure by using Note:
gnutls_certificate_set_x509_simple_pkcs12_file.

In GnuTLS the PKCS #12 structures are handled using the
'gnutls_pkcs12_t' type.  This is an abstract type that may hold several
'gnutls_pkcs12_bag_t' types.  The bag types are the holders of the
actual data, which may be certificates, private keys or encrypted data.
A bag of type encrypted should be decrypted in order for its data to be
accessed.

To reduce the complexity in parsing the structures the simple helper
function Note: gnutls_pkcs12_simple_parse is provided.  For more
advanced uses, manual parsing of the structure is required using the
functions below.

'INT Note: gnutls_pkcs12_get_bag (gnutls_pkcs12_t PKCS12, int INDX, gnutls_pkcs12_bag_t BAG)'
'INT Note: gnutls_pkcs12_verify_mac (gnutls_pkcs12_t PKCS12, const char * PASS)'
'INT Note: gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t BAG, const char * PASS)'
'INT Note: gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t BAG)'

 -- Function: int gnutls_pkcs12_simple_parse (gnutls_pkcs12_t P12, const
          char * PASSWORD, gnutls_x509_privkey_t * KEY,
          gnutls_x509_crt_t ** CHAIN, unsigned int * CHAIN_LEN,
          gnutls_x509_crt_t ** EXTRA_CERTS, unsigned int *
          EXTRA_CERTS_LEN, gnutls_x509_crl_t * CRL, unsigned int FLAGS)
     P12: A pkcs12 type

     PASSWORD: optional password used to decrypt the structure, bags and
     keys.

     KEY: a structure to store the parsed private key.

     CHAIN: the corresponding to key certificate chain (may be 'NULL' )

     CHAIN_LEN: will be updated with the number of additional (may be
     'NULL' )

     EXTRA_CERTS: optional pointer to receive an array of additional
     certificates found in the PKCS12 structure (may be 'NULL' ).

     EXTRA_CERTS_LEN: will be updated with the number of additional
     certs (may be 'NULL' ).

     CRL: an optional structure to store the parsed CRL (may be 'NULL'
     ).

     FLAGS: should be zero or one of GNUTLS_PKCS12_SP_*

     This function parses a PKCS12 structure in 'pkcs12' and extracts
     the private key, the corresponding certificate chain, any
     additional certificates and a CRL. The structures in 'key' ,
     'chain' 'crl' , and 'extra_certs' must not be initialized.

     The 'extra_certs' and 'extra_certs_len' parameters are optional and
     both may be set to 'NULL' .  If either is non-'NULL' , then both
     must be set.  The value for 'extra_certs' is allocated using
     'gnutls_malloc()' .

     Encrypted PKCS12 bags and PKCS8 private keys are supported, but
     only with password based security and the same password for all
     operations.

     Note that a PKCS12 structure may contain many keys and/or
     certificates, and there is no way to identify which key/certificate
     pair you want.  For this reason this function is useful for PKCS12
     files that contain only one key/certificate pair and/or one CRL.

     If the provided structure has encrypted fields but no password is
     provided then this function returns 'GNUTLS_E_DECRYPTION_FAILED' .

     Note that normally the chain constructed does not include self
     signed certificates, to comply with TLS' requirements.  If,
     however, the flag 'GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED' is
     specified then self signed certificates will be included in the
     chain.

     Prior to using this function the PKCS '12' structure integrity must
     be verified using 'gnutls_pkcs12_verify_mac()' .

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.1.0
'INT Note: gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t BAG, unsigned INDX, gnutls_datum_t * DATA)'
'INT Note: gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t BAG, unsigned INDX, gnutls_datum_t * ID)'
'INT Note: gnutls_pkcs12_bag_get_friendly_name (gnutls_pkcs12_bag_t BAG, unsigned INDX, char ** NAME)'

The functions below are used to generate a PKCS #12 structure.  An
example of their usage is shown at Note: PKCS12 structure generation
example.

'INT Note: gnutls_pkcs12_set_bag (gnutls_pkcs12_t PKCS12, gnutls_pkcs12_bag_t BAG)'
'INT Note: gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t BAG, const char * PASS, unsigned int FLAGS)'
'INT Note: gnutls_pkcs12_generate_mac (gnutls_pkcs12_t PKCS12, const char * PASS)'
'INT Note: gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t BAG, gnutls_pkcs12_bag_type_t TYPE, const gnutls_datum_t * DATA)'
'INT Note: gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t BAG, gnutls_x509_crl_t CRL)'
'INT Note: gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t BAG, gnutls_x509_crt_t CRT)'
'INT Note: gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t BAG, unsigned INDX, const gnutls_datum_t * ID)'
'INT Note: gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t BAG, unsigned INDX, const char * NAME)'

OpenSSL encrypted keys
......................

Unfortunately the structures discussed in the previous sections are not
the only structures that may hold an encrypted private key.  For example
the OpenSSL library offers a custom key encryption method.  Those
structures are also supported in GnuTLS with Note:
gnutls_x509_privkey_import_openssl.

 -- Function: int gnutls_x509_privkey_import_openssl
          (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, const
          char * PASSWORD)
     KEY: The data to store the parsed key

     DATA: The DER or PEM encoded key.

     PASSWORD: the password to decrypt the key (if it is encrypted).

     This function will convert the given PEM encrypted to the native
     gnutls_x509_privkey_t format.  The output will be stored in 'key' .

     The 'password' should be in ASCII. If the password is not provided
     or wrong then 'GNUTLS_E_DECRYPTION_FAILED' will be returned.

     If the Certificate is PEM encoded it should have a header of
     "PRIVATE KEY" and the "DEK-Info" header.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.