@node More on certificate authentication
-@chapter More on certificate authentication
+@section More on certificate authentication
@cindex certificate authentication
Certificates are not the only structures involved in a public key
* Managing encrypted keys::
* certtool Invocation:: Invoking certtool
* ocsptool Invocation:: Invoking ocsptool
-* Smart cards and HSMs::
-* Abstract key types::
+* danetool Invocation:: Invoking danetool
@end menu
@node PKCS 10 certificate requests
-@section @acronym{PKCS} #10 certificate requests
+@subsection @acronym{PKCS} #10 certificate requests
@cindex certificate requests
@cindex PKCS #10
The last step ensures that the requester is in
possession of the private key.
-@showfuncE{gnutls_x509_crq_set_version,gnutls_x509_crq_set_dn_by_oid,gnutls_x509_crq_set_key_usage,gnutls_x509_crq_set_key_purpose_oid,gnutls_x509_crq_set_basic_constraints}
+@showfuncF{gnutls_x509_crq_set_version,gnutls_x509_crq_set_dn,gnutls_x509_crq_set_dn_by_oid,gnutls_x509_crq_set_key_usage,gnutls_x509_crq_set_key_purpose_oid,gnutls_x509_crq_set_basic_constraints}
The @funcref{gnutls_x509_crq_set_key} and @funcref{gnutls_x509_crq_sign2}
functions associate the request with a private key and sign it. If a
private key. A certificate request can be later be processed by a CA
which should return a signed certificate.
-@anchor{ex:crq}
+@anchor{ex-crq}
@verbatiminclude examples/ex-crq.c
@node PKIX certificate revocation lists
-@section PKIX certificate revocation lists
+@subsection PKIX certificate revocation lists
@cindex certificate revocation lists
@cindex CRL
A certificate revocation list (CRL) is a structure issued by an authority
-periodically containing a list of revoked certificates serial numbers.
+periodically containing a list of revoked certificates serial numbers.
The CRL structure is signed with the issuing authorities' keys. A typical
CRL contains the fields as shown in @ref{tab:crl}.
Certificate revocation lists are used to complement the expiration date of a certificate,
in order to account for other reasons of revocation, such as compromised keys, etc.
-A certificate request can be generated by
-associating it with a private key, setting the
-subject's information and finally self signing it.
-The last step ensures that the requester is in
-possession of the private key. Each CRL is valid for limited amount of
+Each CRL is valid for limited amount of
time and is required to provide, except for the current issuing time, also
the issuing time of the next update.
@caption{Certificate revocation list fields.}
@end float
+The basic CRL structure functions follow.
+
+@showfuncD{gnutls_x509_crl_init,gnutls_x509_crl_import,gnutls_x509_crl_export,gnutls_x509_crl_export}
+
+@subsubheading Reading a CRL
+
+The most important function that extracts the certificate revocation
+information from a CRL is @funcref{gnutls_x509_crl_get_crt_serial}. Other
+functions that return other fields of the CRL structure are also provided.
-@showfuncE{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial,gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
+@showfuncdesc{gnutls_x509_crl_get_crt_serial}
+
+@showfuncF{gnutls_x509_crl_get_version,gnutls_x509_crl_get_issuer_dn,gnutls_x509_crl_get_issuer_dn2,gnutls_x509_crl_get_this_update,gnutls_x509_crl_get_next_update,gnutls_x509_crl_get_crt_count}
+
+@subsubheading Generation of a CRL
+
+The following functions can be used to generate a CRL.
+
+@showfuncB{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial}
+@showfuncC{gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign}
functions sign the revocation list with a private key. The latter function
@showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id}
@node OCSP certificate status checking
-@section @acronym{OCSP} certificate status checking
+@subsection @acronym{OCSP} certificate status checking
@cindex certificate status
@cindex Online Certificate Status Protocol
@cindex OCSP
identified @xcite{RIVESTCRL}.
The Online Certificate Status Protocol, or @acronym{OCSP} @xcite{RFC2560},
-is a widely implemented protocol to perform certificate revocation status
+is a widely implemented protocol which performs certificate revocation status
checking. An application that wish to verify the
identity of a peer will verify the certificate against a set of
trusted certificates and then check whether the certificate is listed
in a CRL and/or perform an OCSP check for the certificate.
+Note that in the context of a TLS session the server may provide an
+OCSP response that will be used during the TLS certificate verification
+(see @funcref{gnutls_certificate_verify_peers2}).
+You may obtain this response using @funcref{gnutls_ocsp_status_request_get}.
+
Before performing the OCSP query, the application will need to figure
out the address of the OCSP server. The OCSP server address can be
provided by the local user in manual configuration or may be stored
-in the certificate that is being checked. The latter is due to
-an extension field called the Authority Information Access (AIA) which
-may hold the location of the OCSP responder in
-the access method called @code{id-ad-ocsp}. The following function
+in the certificate that is being checked. When stored in a certificate
+the OCSP server is in the extension field called the Authority Information
+Access (AIA). The following function
extracts this information from a certificate.
@showfuncA{gnutls_x509_crt_get_authority_info_access}
There are several functions in GnuTLS for creating and manipulating
OCSP requests and responses. The general idea is that a client
-application create an OCSP request object, store some information
-about the certificate to check in the request, and then export the
+application creates an OCSP request object, stores some information
+about the certificate to check in the request, and then exports the
request in DER format. The request will then need to be sent to the
OCSP responder, which needs to be done by the application (GnuTLS does
not send and receive OCSP packets). Normally an OCSP response is
@showfuncE{gnutls_ocsp_req_init,gnutls_ocsp_req_deinit,gnutls_ocsp_req_import,gnutls_ocsp_req_export,gnutls_ocsp_req_print}
-There are two interfaces for setting the identity of a certificate in
-a OCSP request, the first being a low-level function when you have the
+To generate an OCSP request the issuer name hash, issuer key hash, and
+the checked certificate's serial number are required. There are two
+interfaces available for setting those in an OCSP request.
+The is a low-level function when you have the
issuer name hash, issuer key hash, and certificate serial number in
-binary form. The second is usually more useful if you have the
+binary form. The second is more useful if you have the
certificate (and its issuer) in a @code{gnutls_x509_crt_t} type.
-There is also a function to extract this information from an OCSP
+There is also a function to extract this information from existing an OCSP
request.
@showfuncC{gnutls_ocsp_req_add_cert_id,gnutls_ocsp_req_add_cert,gnutls_ocsp_req_get_cert_id}
Each OCSP request may contain a number of extensions. Extensions are
identified by an Object Identifier (OID) and an opaque data buffer
-whose syntax and semantics is implied by the OID.
+whose syntax and semantics is implied by the OID. You can extract or
+set those extensions using the following functions.
@showfuncB{gnutls_ocsp_req_get_extension,gnutls_ocsp_req_set_extension}
@showfuncC{gnutls_ocsp_req_get_nonce,gnutls_ocsp_req_set_nonce,gnutls_ocsp_req_randomize_nonce}
-The OCSP response structures is a bit more complex than the request.
-The important ASN.1 structure is as follows. In practice, all OCSP
-responses contain a Basic OCSP response sub-structure.
+The OCSP response structures is a complex structure. A simplified overview
+of it is in @ref{tab:ocsp-response}. Note that a response may contain
+information on multiple certificates.
+
+@float Table,tab:ocsp-response
+@multitable @columnfractions .2 .7
+
+@headitem Field @tab Description
+
+@item version @tab
+The OCSP response version number (typically 1).
+
+@item responder ID @tab
+An identifier of the responder (DN name or a hash of its key).
+
+@item issue time @tab
+The time the response was generated.
+
+@item thisUpdate @tab
+The issuing time of the revocation information.
+
+@item nextUpdate @tab
+The issuing time of the revocation information that will update that one.
+
+@item @tab Revoked certificates
+
+@item certificate status @tab
+The status of the certificate.
+
+@item certificate serial @tab
+The certificate's serial number.
+
+@item revocationTime @tab
+The time the certificate was revoked.
+
+@item revocationReason @tab
+The reason the certificate was revoked.
+
+@end multitable
+@caption{The most important OCSP response fields.}
+@end float
-@example
-OCSPResponse ::= SEQUENCE @{
- responseStatus OCSPResponseStatus,
- responseBytes [0] EXPLICIT ResponseBytes OPTIONAL @}
-
-OCSPResponseStatus ::= ENUMERATED @{
- successful (0), --Response has valid confirmations
- malformedRequest (1), --Illegal confirmation request
- internalError (2), --Internal error in issuer
- tryLater (3), --Try again later
- --(4) is not used
- sigRequired (5), --Must sign the request
- unauthorized (6) --Request unauthorized @}
-
-ResponseBytes ::= SEQUENCE @{
- responseType OBJECT IDENTIFIER,
- response OCTET STRING @}
-
-id-pkix-ocsp-basic OBJECT IDENTIFIER ::= @{ id-pkix-ocsp 1 @}
-
-BasicOCSPResponse ::= SEQUENCE @{
- tbsResponseData ResponseData,
- signatureAlgorithm AlgorithmIdentifier,
- signature BIT STRING,
- certs [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL @}
-
-ResponseData ::= SEQUENCE @{
- version [0] EXPLICIT Version DEFAULT v1,
- responderID ResponderID,
- producedAt GeneralizedTime,
- responses SEQUENCE OF SingleResponse,
- responseExtensions [1] EXPLICIT Extensions OPTIONAL @}
-
-ResponderID ::= CHOICE @{
- byName [1] Name,
- byKey [2] KeyHash @}
-
-KeyHash ::= OCTET STRING -- SHA-1 hash of responder's public key
-(excluding the tag and length fields)
-
-SingleResponse ::= SEQUENCE @{
- certID CertID,
- certStatus CertStatus,
- thisUpdate GeneralizedTime,
- nextUpdate [0] EXPLICIT GeneralizedTime OPTIONAL,
- singleExtensions [1] EXPLICIT Extensions OPTIONAL @}
-
-CertStatus ::= CHOICE @{
- good [0] IMPLICIT NULL,
- revoked [1] IMPLICIT RevokedInfo,
- unknown [2] IMPLICIT UnknownInfo @}
-
-RevokedInfo ::= SEQUENCE @{
- revocationTime GeneralizedTime,
- revocationReason [0] EXPLICIT CRLReason OPTIONAL @}
-@end example
We provide basic functions for initialization, importing, exporting
-and deallocating OCSP responses. The Basic OCSP Response structure is
-automatically parsed when an OCSP Response is imported.
+and deallocating OCSP responses.
@showfuncE{gnutls_ocsp_resp_init,gnutls_ocsp_resp_deinit,gnutls_ocsp_resp_import,gnutls_ocsp_resp_export,gnutls_ocsp_resp_print}
-The OCSP response needs to be verified against some set of trust
-anchors before it can be relied upon.
+The utility function that extracts the revocation as well as other information
+from a response is shown below.
+
+@showfuncdesc{gnutls_ocsp_resp_get_single}
-@showfuncB{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct}
+The possible revocation reasons available in an OCSP response are shown
+below.
+
+@showenumdesc{gnutls_x509_crl_reason_t,The revocation reasons}
+
+Note, that the OCSP response needs to be verified against some set of trust
+anchors before it can be relied upon. It is also important to check
+whether the received OCSP response corresponds to the certificate being checked.
+
+@showfuncC{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct,gnutls_ocsp_resp_check_crt}
@node Managing encrypted keys
-@section Managing encrypted keys
+@subsection Managing encrypted keys
@cindex Encrypted keys
-Transferring or storing private keys in plain might not be a
-good idea. Any access on the keys becomes a fatal compromise.
+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 @ref{Smart cards and HSMs})
could solve the storage problem but it is not always practical
-or efficient enough. This section describes alternative ways
-that involve encryption of the private keys to store and
-transfer.
-
-There are two alternatives to use for key encryption,
-PKCS #8 and #12 methods of private key encryption. The PKCS #8
-method only allows encryption of the private key, whilst the
-PKCS #12 method allows in addition the bundling of other
-data into the structure. That could be bundling together the
-certificate as well as the trusted CA certificate.
-
-@subheading @acronym{PKCS} #8 structures
+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.
+
+@subsubheading 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.
+
+@showfuncdesc{gnutls_privkey_import_x509_raw}
+
+@showfuncdesc{gnutls_x509_privkey_import2}
+
+Any keys imported using those functions can be imported to a certificate
+credentials structure using @funcref{gnutls_certificate_set_key}, or alternatively
+they can be directly imported using @funcref{gnutls_certificate_set_x509_key_file2}.
+
+@subsubheading @acronym{PKCS} #8 structures
@cindex PKCS #8
PKCS #8 keys can be imported and exported as normal private keys using
encryption scheme. Keys encrypted with the obsolete PBES1 scheme cannot
be decrypted.
-@showfuncB{gnutls_x509_privkey_import_pkcs8,gnutls_x509_privkey_export_pkcs8}
+@showfuncC{gnutls_x509_privkey_import_pkcs8,gnutls_x509_privkey_export_pkcs8,gnutls_x509_privkey_export2_pkcs8}
@showenumdesc{gnutls_pkcs_encrypt_flags_t,Encryption flags}
-@subheading @acronym{PKCS} #12 structures
+@subsubheading @acronym{PKCS} #12 structures
@cindex PKCS #12
A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's
private keys and certificates. It is commonly used in browsers to
-export and import the user's identities.
+export and import the user's identities. A file containing such a key can
+be directly imported to a certificate credentials structure by using
+@funcref{gnutls_certificate_set_x509_simple_pkcs12_file}.
In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
using the @code{gnutls_pkcs12_t} type. This is an abstract type that
keys or encrypted data. A bag of type encrypted should be decrypted
in order for its data to be accessed.
-@showfuncC{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt}
+To reduce the complexity in parsing the structures the simple
+helper function @funcref{gnutls_pkcs12_simple_parse} is provided. For more
+advanced uses, manual parsing of the structure is required using the
+functions below.
-@showfuncD{gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
+@showfuncD{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt,gnutls_pkcs12_bag_get_count}
+
+@showfuncdesc{gnutls_pkcs12_simple_parse}
+@showfuncC{gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
The functions below are used to generate a PKCS #12 structure. An example
-of their usage is also shown.
+of their usage is shown at @ref{PKCS12 structure generation example}.
@showfuncC{gnutls_pkcs12_set_bag,gnutls_pkcs12_bag_encrypt,gnutls_pkcs12_generate_mac}
@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}
-@verbatiminclude examples/ex-pkcs12.c
+@subsubheading OpenSSL encrypted keys
+@cindex 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 @funcref{gnutls_x509_privkey_import_openssl}.
+
+@showfuncdesc{gnutls_x509_privkey_import_openssl}
@include invoke-certtool.texi
@include invoke-ocsptool.texi
-@node Smart cards and HSMs
-@section Smart cards and HSMs
-@cindex PKCS #11 tokens
-@cindex hardware tokens
-@cindex hardware security modules
-@cindex smart cards
-
-In this section we present the smart-card and hardware security module (HSM) support
-in @acronym{GnuTLS} using @acronym{PKCS} #11 @xcite{PKCS11}. Hardware security
-modules and smart cards provide a way to store private keys and perform
-operations on them without exposing them. This decouples cryptographic
-keys from the applications that use them and provide an additional
-security layer against cryptographic key extraction.
-Since this can also be achieved in software components such as in Gnome keyring,
-we will use the term security module to describe any cryptographic key
-separation subsystem.
-
-@acronym{PKCS} #11 is plugin API allowing applications to access cryptographic
-operations on a security module, as well as to objects residing on it. PKCS
-#11 modules exist for hardware tokens such as smart cards@footnote{@url{http://www.opensc-project.org}},
-the trusted
-platform module (TPM)@footnote{@url{http://trousers.sourceforge.net/}}
-as well as for software modules like @acronym{Gnome Keyring}.
-The objects residing on a security module may be certificates, public keys,
-private keys or secret keys. Of those certificates and public/private key
-pairs can be used with @acronym{GnuTLS}. PKCS #11's main advantage is that
-it allows operations on private key objects such as decryption
-and signing without exposing the key.
-
-Moreover @acronym{PKCS} #11 can be (ab)used to allow all applications in the same operating system to access
-shared cryptographic keys and certificates in a uniform way, as in @ref{fig:pkcs11-vision}.
-That way applications could load their trusted certificate list, as well as user
-certificates from a common PKCS #11 module. Such a provider exists in the @acronym{Gnome}
-system, being the @acronym{Gnome Keyring}.
-
-@float Figure,fig:pkcs11-vision
-@image{pkcs11-vision,9cm}
-@caption{PKCS #11 module usage.}
-@end float
-
-@menu
-* PKCS11 Initialization::
-* Reading objects::
-* Writing objects::
-* Using a PKCS11 token with TLS::
-* p11tool Invocation:: Invoking p11tool
-@end menu
-
-@node PKCS11 Initialization
-@subsection Initialization
-To allow all the @acronym{GnuTLS} applications to access @acronym{PKCS} #11 tokens
-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:
-
-@example
-module: /usr/lib/opensc-pkcs11.so
-@end example
-
-If you use this file, then there is no need for other initialization in
-@acronym{GnuTLS}, except for the PIN and token functions. Those allow retrieving a PIN
-when accessing a protected object, such as a private key, as well as probe
-the user to insert the token. All the initialization functions are below.
-
-@showfuncdesc{gnutls_pkcs11_init}
-@showfuncC{gnutls_pkcs11_set_token_function,gnutls_pkcs11_set_pin_function,gnutls_pkcs11_add_provider}
-
-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 @acronym{p11-kit}
-that provides a middleware to control access to resources over the
-multiple users.
-
-Moreover PKCS #11 modules must be reinitialized on the child processes
-after a @funcintref{fork}. @acronym{GnuTLS} provides @funcref{gnutls_pkcs11_reinit}
-to be called for this purpose.
-
-@showfuncdesc{gnutls_pkcs11_reinit}
-
-@node Reading objects
-@subsection Reading objects
-
-All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by
-URLs as described in @xcite{PKCS11URI}.
-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:
-
-@example
-pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
-manufacturer=EnterSafe;object=test1;objecttype=public;\
-id=32f153f3e37990b08624141077ca5dec2d15faed
-@end example
-
-while the smart card itself can be referenced as:
-@example
-pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
-@end example
-
-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_import_url,gnutls_pkcs11_obj_export_url}
-
-@showfuncdesc{gnutls_pkcs11_obj_get_info}
-
-@showfuncC{gnutls_x509_crt_import_pkcs11,gnutls_x509_crt_import_pkcs11_url,gnutls_x509_crt_list_import_pkcs11}
-
-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.
-
-@showfuncE{gnutls_pkcs11_token_init,gnutls_pkcs11_token_get_url,gnutls_pkcs11_token_get_info,gnutls_pkcs11_token_get_flags,gnutls_pkcs11_token_set_pin}
-
-The following examples demonstrate the usage of the API. The first example
-will list all available PKCS #11 tokens in a system and the latter will
-list all certificates in a token that have a corresponding private key.
-
-@example
-int i;
-char* url;
-
-gnutls_global_init();
-
-for (i=0;;i++)
- @{
- ret = gnutls_pkcs11_token_get_url(i, &url);
- if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
- break;
-
- if (ret < 0)
- exit(1);
-
- fprintf(stdout, "Token[%d]: URL: %s\n", i, url);
- gnutls_free(url);
- @}
-gnutls_global_deinit();
-@end example
-
-@verbatiminclude examples/ex-pkcs11-list.c
-
-@node Writing objects
-@subsection Writing objects
-
-With @acronym{GnuTLS} you can copy existing private keys and certificates
-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_copy_x509_privkey}
-
-@showfuncdesc{gnutls_pkcs11_copy_x509_crt}
-@showfuncdesc{gnutls_pkcs11_delete_url}
-
-
-@node Using a PKCS11 token with TLS
-@subsection Using a @acronym{PKCS} #11 token with TLS
-
-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.
-
-@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}
-@showfuncdesc{gnutls_certificate_set_x509_system_trust}
-
-@include invoke-p11tool.texi
-
-@node Abstract key types
-@section Abstract key types
-@cindex abstract types
-
-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
-to sign an X.509 certificate with a key that resides in a token the following steps must be
-used.
-
-@example
-#inlude <gnutls/abstract.h>
-#inlude <gnutls/pkcs11.h>
-
-void sign_cert( gnutls_x509_crt_t to_be_signed)
-@{
-gnutls_pkcs11_privkey_t ca_key;
-gnutls_x509_crt_t ca_cert;
-gnutls_privkey_t abs_key;
-
- /* load the PKCS #11 key and certificates */
- gnutls_pkcs11_privkey_init(&ca_key);
- gnutls_pkcs11_privkey_import_url(ca_key, key_url);
-
- gnutls_x509_crt_init(&ca_cert);
- gnutls_x509_crt_import_pkcs11_url(&ca_cert, cert_url);
-
- /* initialize the abstract key */
- gnutls_privkey_init(&abs_key);
- gnutls_privkey_import_pkcs11(abs_key, ca_key);
-
- /* sign the certificate to be signed */
- gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, ca_key,
- GNUTLS_DIG_SHA256, 0);
-@}
-@end example
-
-@menu
-* Abstract public keys::
-* Abstract private keys::
-* Operations::
-@end menu
-
-
-@node Abstract public keys
-@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.
-
-@showfuncdesc{gnutls_pubkey_import_x509}
-@showfuncE{gnutls_pubkey_import_openpgp,gnutls_pubkey_import_pkcs11,gnutls_pubkey_import_pkcs11_url,gnutls_pubkey_import_privkey,gnutls_pubkey_import}
-@showfuncdesc{gnutls_pubkey_export}
-
-Additional functions are available that will return
-information over a public key.
-
-@showfuncC{gnutls_pubkey_get_pk_algorithm,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id}
-
-@node Abstract private keys
-@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.
-
-@showfuncC{gnutls_privkey_import_x509,gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11}
-
-@showfuncB{gnutls_privkey_get_pk_algorithm,gnutls_privkey_get_type}
-
-In order to support cryptographic operations using
-an external API, the following function is provided.
-This allows for a simple extensibility API without
-resorting to @acronym{PKCS} #11.
-
-@showfuncdesc{gnutls_privkey_import_ext}
-
-@node Operations
-@subsection Operations
-The abstract key types can be used to access signing and
-signature verification operations with the underlying keys.
-
-@showfuncdesc{gnutls_pubkey_verify_data2}
-@showfuncdesc{gnutls_pubkey_verify_hash2}
-@showfuncdesc{gnutls_pubkey_encrypt_data}
-
-@showfuncdesc{gnutls_privkey_sign_data}
-@showfuncdesc{gnutls_privkey_sign_hash}
-@showfuncdesc{gnutls_privkey_decrypt_data}
-
-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}
-@showfuncC{gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
+@include invoke-danetool.texi
projects / platform / upstream / gnutls.git / blobdiff