@cindex Certificate authentication
@menu
-* The X.509 trust model::
-* The OpenPGP trust model::
+* X.509 certificates::
+* OpenPGP certificates::
* Hardware tokens::
* Abstract key types::
* Digital signatures::
@end menu
-@node The X.509 trust model
-@section The @acronym{X.509} trust model
+@node X.509 certificates
+@section @acronym{X.509} certificates
@cindex @acronym{X.509} certificates
The @acronym{X.509} protocols rely on a hierarchical trust model. In
acceptable. The framework is illustrated on @ref{fig:x509}.
@menu
-* X.509 certificates::
+* X.509 certificate structure::
* Verifying X.509 certificate paths::
* Verifying a certificate in the context of TLS session::
* Certificate requests::
* PKCS 12 structures::
@end menu
-@node X.509 certificates
-@subsection @acronym{X.509} certificates
+@node X.509 certificate structure
+@subsection @acronym{X.509} certificate structure
An @acronym{X.509} certificate usually contains information about the
certificate holder, the signer, a unique serial number, expiration
@acronym{PKCS} #10 @xcite{RFC2986}. Other formats of certificate requests
are not currently supported.
+@showfuncB{gnutls_x509_crq_init, gnutls_x509_crq_deinit}
+
+@showfuncdesc{gnutls_x509_crq_import}
+@showfuncdesc{gnutls_x509_crq_export}
+
+A certificate request can be generated by
+associating it with a private key, setting the
+subject's information and self signing it.
+
+@showfuncdesc{gnutls_x509_crq_set_version}
+@showfuncdesc{gnutls_x509_crq_set_dn_by_oid}
+@showfuncdesc{gnutls_x509_crq_set_key_usage}
+@showfuncdesc{gnutls_x509_crq_set_key_purpose_oid}
+@showfuncdesc{gnutls_x509_crq_set_basic_constraints}
+
+The following two functions associate the request with
+a private key and sign it. If a request is to be signed
+with a key residing in a token it is recommended to use
+the signing functions shown in @ref{Abstract key types}.
+
+@showfuncdesc{gnutls_x509_crq_set_key}
+@showfuncdesc{gnutls_x509_crq_sign2}
+
The following example is about generating a certificate request, and a
private key. A certificate request can be later be processed by a CA,
which should return a signed certificate.
keys or encrypted data. A bag of type encrypted should be decrypted
in order for its data to be accessed.
+@showfuncB{gnutls_pkcs12_init, gnutls_pkcs12_deinit}
+
+The following functions are available to read a @acronym{PKCS} #12
+structure.
+
+@showfuncdesc{gnutls_pkcs12_import}
+@showfuncdesc{gnutls_pkcs12_get_bag}
+@showfuncdesc{gnutls_pkcs12_verify_mac}
+@showfuncdesc{gnutls_pkcs12_bag_decrypt}
+
+@showfuncB{gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit}
+
+@showfuncD{gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
+
+To generate a structure the functions below may be used.
+
+@showfuncdesc{gnutls_pkcs12_set_bag}
+@showfuncdesc{gnutls_pkcs12_bag_encrypt}
+@showfuncdesc{gnutls_pkcs12_generate_mac}
+@showfuncdesc{gnutls_pkcs12_export}
+@showfuncE{gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name}
+
An example of a @acronym{PKCS} #12 structure generation can be found
below.
@verbatiminclude examples/ex-pkcs12.c
-@node The OpenPGP trust model
-@section The @acronym{OpenPGP} trust model
-@cindex @acronym{OpenPGP} keys
+@node OpenPGP certificates
+@section @acronym{OpenPGP} certificates
+@cindex @acronym{OpenPGP} certificates
The @acronym{OpenPGP} key authentication relies on a distributed trust
model, called the ``web of trust''. The ``web of trust'' uses a
enough, and signs other people's keys without being sure that they
belong to the actual owner.
-@subsection @acronym{OpenPGP} keys
+@subsection @acronym{OpenPGP} certificate structure
In @acronym{GnuTLS} the @acronym{OpenPGP} key structures
@xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type
@subsection Initialization
To allow all the @acronym{GnuTLS} applications to access @acronym{PKCS} #11 tokens
-you can use a configuration per module, such as @code{/etc/pkcs11/modules/mymodule.conf}.
-This file has the following format:
+you can use a configuration per module, stored in @code{/etc/pkcs11/modules/}.
+These are the configuration files of @acronym{p11-kit}@footnote{@url{http://p11-glue.freedesktop.org/}}.
+For example a file that will load the @acronym{OpenSC} module, could be named
+@code{/etc/pkcs11/modules/opensc} and contain the following:
@smallexample
module: /usr/lib/opensc-pkcs11.so
the user to insert the token. All the initialization functions are below.
@showfuncdesc{gnutls_pkcs11_init}
-@showfuncdesc{gnutls_pkcs11_deinit}
@showfuncdesc{gnutls_pkcs11_set_token_function}
@showfuncdesc{gnutls_pkcs11_set_pin_function}
@showfuncdesc{gnutls_pkcs11_add_provider}
+@showfuncA{gnutls_pkcs11_deinit}
Note that due to limitations of @acronym{PKCS} #11 there are issues when multiple libraries
-are sharing a module. To avoid this problem GnuTLS uses p11-kit@footnote{@url{http://p11-glue.freedesktop.org/}}
+are sharing a module. To avoid this problem GnuTLS uses @acronym{p11-kit}
that provides a middleware to control access to resources over the
multiple users.
@subsection Reading objects
All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by
-URLs as described in @code{draft-pechanec-pkcs11uri-03}. For example a public
+URLs as described in @code{draft-pechanec-pkcs11uri-05}.
+This allows for a consistent naming of objects across systems and applications
+in the same system. For example a public
key on a smart card may be referenced as:
@smallexample
pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
@end smallexample
-
-@acronym{PKCS} #11 objects can be accessed with the functions shown below.
+Objects stored in a @acronym{PKCS} #11 token can be extracted
+if they are not marked as sensitive. Usually only private keys are marked as
+sensitive and cannot be extracted, while certificates and other data can
+be retrieved. The functions that can be used to access objects
+are shown below.
@showfuncB{gnutls_pkcs11_obj_init,gnutls_pkcs11_obj_deinit}
@showfuncC{gnutls_x509_crt_import_pkcs11,gnutls_x509_crt_import_pkcs11_url,gnutls_x509_crt_list_import_pkcs11}
-Functions that relate to token handling are shown below.
+Properties of the physical token can also be accessed and altered with @acronym{GnuTLS}.
+For example data in a token can be erased (initialized), PIN can be altered, etc.
@showfuncdesc{gnutls_pkcs11_token_init}
@showfuncdesc{gnutls_pkcs11_token_set_pin}
@subsection Writing objects
With @acronym{GnuTLS} you can copy existing private keys and certificates
-to a token. This can be achieved with the following functions
+to a token. Note that when copying private keys it is recommended to mark
+them as sensitive using the @code{GNUTLS_\-PKCS11_OBJ_\-FLAG_\-MARK_\-SENSITIVE}
+to prevent its extraction. An object can be marked as private using the flag
+@code{GNUTLS_\-PKCS11_OBJ_\-FLAG_\-MARK_\-PRIVATE}, to require PIN to be
+entered before accessing the object (for operations or otherwise).
@showfuncdesc{gnutls_pkcs11_delete_url}
@showfuncdesc{gnutls_pkcs11_copy_x509_privkey}
It is possible to use a @acronym{PKCS} #11 token to a TLS
session, as shown in @ref{ex:pkcs11-client}. In addition
the following functions can be used to load PKCS #11 key and
-certificates, by specifying a PKCS #11 URL instead of a filename.
+certificates by specifying a PKCS #11 URL instead of a filename.
@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}
Since there are many forms of a public or private keys supported by @acronym{GnuTLS} such as
@acronym{X.509}, @acronym{OpenPGP}, or @acronym{PKCS} #11 it is desirable to allow common operations
on them. For these reasons the abstract @code{gnutls_privkey_t} and @code{gnutls_pubkey_t} were
-introduced in @code{gnutls/abstract.h} header. Those types are initialized using a specific type of key and then can be used to
-perform operations in an abstract way. For example in order for someone to sign an X.509 certificate
-with a key that resides in a smart he has to follow the steps below:
+introduced in @code{gnutls/abstract.h} header. Those types are initialized using a specific type of
+key and then can be used to perform operations in an abstract way. For example in order for someone
+to sign an X.509 certificate with a key that resides in a smart he has to follow the steps below:
@example
#inlude <gnutls/abstract.h>
@}
@end example
+@subsection Public keys
+An abstract @code{gnutls_pubkey_t} can be initialized
+using the functions below. It can be imported through
+an existing structure like @code{gnutls_x509_crt_t},
+or through an ASN.1 encoding of the X.509 @code{SubjectPublicKeyInfo}
+sequence.
+
+@showfuncB{gnutls_pubkey_init,gnutls_pubkey_deinit}
+
+@showfuncdesc{gnutls_pubkey_import_x509}
+@showfuncdesc{gnutls_pubkey_import_openpgp}
+@showfuncdesc{gnutls_pubkey_import_pkcs11}
+@showfuncdesc{gnutls_pubkey_import_pkcs11_url}
+@showfuncdesc{gnutls_pubkey_import_privkey}
+@showfuncdesc{gnutls_pubkey_import}
+@showfuncdesc{gnutls_pubkey_export}
+
+Additional functions are available that will return
+information over a public key.
+
+@showfuncdesc{gnutls_pubkey_get_pk_algorithm}
+@showfuncdesc{gnutls_pubkey_get_preferred_hash_algorithm}
+@showfuncdesc{gnutls_pubkey_get_key_id}
+
+@subsection Private keys
+An abstract @code{gnutls_privkey_t} can be initialized
+using the functions below. It can be imported through
+an existing structure like @code{gnutls_x509_privkey_t},
+but unlike public keys it cannot be exported. That is
+to allow abstraction over @acronym{PKCS} #11 keys that
+are not extractable.
+
+@showfuncdesc{gnutls_privkey_init,gnutls_privkey_deinit}
+@showfuncdesc{gnutls_privkey_import_x509}
+@showfuncdesc{gnutls_privkey_import_openpgp}
+@showfuncdesc{gnutls_privkey_import_pkcs11}
+
+Other information on the private key can be accessed using
+the following functions.
+
+@showfuncdesc{gnutls_privkey_get_pk_algorithm}
+@showfuncdesc{gnutls_privkey_get_type}
+
+@subsection Operations
+The abstract key types can be used to access signing and
+signature verification operations on the underlying keys.
+
+@showfuncdesc{gnutls_pubkey_verify_data2}
+@showfuncdesc{gnutls_pubkey_verify_hash}
+@showfuncdesc{gnutls_privkey_sign_data}
+@showfuncdesc{gnutls_privkey_sign_hash}
+
+Signing existing structures, such as certificates, CRLs,
+or certificate requests, as well as associating public
+keys with structures is also possible using the
+key abstractions.
+
+@showfuncdesc{gnutls_x509_crq_set_pubkey}
+@showfuncdesc{gnutls_x509_crt_set_pubkey}
+@showfuncdesc{gnutls_x509_crt_privkey_sign}
+@showfuncdesc{gnutls_x509_crl_privkey_sign}
+@showfuncdesc{gnutls_x509_crq_privkey_sign}
@node Digital signatures
@section Digital signatures
projects / thirdparty / gnutls.git / commitdiff
