From: Nikos Mavrogiannopoulos Date: Fri, 12 Aug 2011 08:50:19 +0000 (+0200) Subject: Documentation updates. gnutls_x509_crq_sign2() and gnutls_x509_crl_sign2() were remov... X-Git-Tag: gnutls_3_0_1~15^2~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c5444982b322a1917b477a2053845bc9fab970ad;p=thirdparty%2Fgnutls.git Documentation updates. gnutls_x509_crq_sign2() and gnutls_x509_crl_sign2() were removed from the deprecate list to ease generation of crl and crq structures. --- diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi index 1d1209a0e6..f42fba2154 100644 --- a/doc/cha-auth.texi +++ b/doc/cha-auth.texi @@ -45,7 +45,7 @@ we elaborate on supported authentication methods. @acronym{X.509} certificates contain the public parameters, of a public key algorithm, and an authority's signature, which proves the -authenticity of the parameters. See @ref{The X.509 trust model}, for +authenticity of the parameters. See @ref{X.509 certificates}, for more information on @acronym{X.509} protocols. @subsection Authentication using @acronym{OpenPGP} keys @@ -57,7 +57,7 @@ whether a signer is trusted the key is considered trusted or not. @acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is based on the @xcite{TLSPGP} proposal. -More information on the @acronym{OpenPGP} trusted model is provided in @ref{The OpenPGP trust model}. +More information on the @acronym{OpenPGP} trusted model is provided in @ref{OpenPGP certificates}. For a more detailed introduction to @acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}. @subsection Using certificate authentication @@ -111,7 +111,7 @@ has been used, to verify the certificate's signature. An alternative way, which reports a more detailed verification output, is to use @funcref{gnutls_certificate_get_peers} to obtain the raw certificate of the peer and verify it using the -functions discussed in @ref{The X.509 trust model}. +functions discussed in @ref{X.509 certificates}. @showfuncdesc{gnutls_certificate_verify_peers2} diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index 30e9619aaa..c36cf9ae14 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -3,15 +3,15 @@ @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 @@ -30,15 +30,15 @@ that case only the certificates issued by the trusted authorities are 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 @@ -278,6 +278,29 @@ password. @acronym{GnuTLS} supports the requests defined in @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. @@ -300,14 +323,36 @@ 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. +@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 @@ -337,7 +382,7 @@ only Kevin, for some reason. A reason could be that Bob is lazy 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 @@ -422,8 +467,10 @@ shared cryptographic keys and certificates in a uniform way, as in @ref{fig:pkcs @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 @@ -435,20 +482,22 @@ 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} -@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 @@ -462,8 +511,11 @@ while the smart card itself can be referenced as: 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} @@ -479,7 +531,8 @@ pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe @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} @@ -517,7 +570,11 @@ private key. @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} @@ -529,7 +586,7 @@ to a token. This can be achieved with the following functions 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} @@ -541,9 +598,9 @@ certificates, by specifying a PKCS #11 URL instead of a filename. 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 @@ -572,6 +629,68 @@ gnutls_privkey_t abs_key; @} @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 diff --git a/doc/examples/ex-crq.c b/doc/examples/ex-crq.c index 6f92f113e1..f452460eab 100644 --- a/doc/examples/ex-crq.c +++ b/doc/examples/ex-crq.c @@ -21,7 +21,6 @@ main (void) { gnutls_x509_crq_t crq; gnutls_x509_privkey_t key; - gnutls_privkey_t pkey; /* object used for signing */ unsigned char buffer[10 * 1024]; size_t buffer_size = sizeof (buffer); unsigned int bits; @@ -34,7 +33,6 @@ main (void) gnutls_x509_crq_init (&crq); gnutls_x509_privkey_init (&key); - gnutls_privkey_init (&pkey); /* Generate an RSA key of moderate security. */ @@ -63,8 +61,7 @@ main (void) /* Self sign the certificate request. */ - gnutls_privkey_import_x509 (pkey, key, 0); - gnutls_x509_crq_privkey_sign (crq, pkey, GNUTLS_DIG_SHA1, 0); + gnutls_x509_crq_sign2 (crq, key, GNUTLS_DIG_SHA1, 0); /* Export the PEM encoded certificate request, and * display it. diff --git a/lib/gnutls_pubkey.c b/lib/gnutls_pubkey.c index 846e385b6c..d672309969 100644 --- a/lib/gnutls_pubkey.c +++ b/lib/gnutls_pubkey.c @@ -759,7 +759,8 @@ gnutls_pubkey_get_pk_ecc_raw (gnutls_pubkey_t key, gnutls_ecc_curve_t *curve, * @format: One of DER or PEM * * This function will convert the given DER or PEM encoded Public key - * to the native gnutls_pubkey_t format.The output will be stored * in @ key. + * to the native gnutls_pubkey_t format.The output will be stored + * in @key. * If the Certificate is PEM encoded it should have a header of "PUBLIC KEY". * * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a diff --git a/lib/includes/gnutls/compat.h b/lib/includes/gnutls/compat.h index 9795857c93..918a40be02 100644 --- a/lib/includes/gnutls/compat.h +++ b/lib/includes/gnutls/compat.h @@ -263,11 +263,6 @@ gnutls_sign_callback_get (gnutls_session_t session, void **userdata) _GNUTLS_GCC_ATTR_DEPRECATED; /* gnutls_x509_crq_privkey_sign() */ - int gnutls_x509_crq_sign2 (gnutls_x509_crq_t crq, - gnutls_x509_privkey_t key, - gnutls_digest_algorithm_t dig, - unsigned int flags) - _GNUTLS_GCC_ATTR_DEPRECATED; int gnutls_x509_crq_sign (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key) _GNUTLS_GCC_ATTR_DEPRECATED; @@ -278,12 +273,6 @@ gnutls_sign_callback_get (gnutls_session_t session, void **userdata) gnutls_x509_crt_t issuer, gnutls_x509_privkey_t issuer_key) _GNUTLS_GCC_ATTR_DEPRECATED; - int gnutls_x509_crl_sign2 (gnutls_x509_crl_t crl, - gnutls_x509_crt_t issuer, - gnutls_x509_privkey_t issuer_key, - gnutls_digest_algorithm_t dig, - unsigned int flags) - _GNUTLS_GCC_ATTR_DEPRECATED; /* functions to set priority of cipher suites */ diff --git a/lib/includes/gnutls/x509.h b/lib/includes/gnutls/x509.h index d3d510b9ea..0a0617ba33 100644 --- a/lib/includes/gnutls/x509.h +++ b/lib/includes/gnutls/x509.h @@ -190,6 +190,12 @@ extern "C" int gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t dst, gnutls_x509_crt_t src); + int gnutls_x509_crl_sign2 (gnutls_x509_crl_t crl, + gnutls_x509_crt_t issuer, + gnutls_x509_privkey_t issuer_key, + gnutls_digest_algorithm_t dig, + unsigned int flags); + time_t gnutls_x509_crt_get_activation_time (gnutls_x509_crt_t cert); time_t gnutls_x509_crt_get_expiration_time (gnutls_x509_crt_t cert); int gnutls_x509_crt_get_serial (gnutls_x509_crt_t cert, void *result, @@ -730,6 +736,11 @@ extern "C" /* Certificate request stuff. */ + int gnutls_x509_crq_sign2 (gnutls_x509_crq_t crq, + gnutls_x509_privkey_t key, + gnutls_digest_algorithm_t dig, + unsigned int flags); + int gnutls_x509_crq_print (gnutls_x509_crq_t crq, gnutls_certificate_print_formats_t format, gnutls_datum_t * out); diff --git a/lib/pkcs11.c b/lib/pkcs11.c index a1a7d798d6..f8be3344c6 100644 --- a/lib/pkcs11.c +++ b/lib/pkcs11.c @@ -1608,7 +1608,7 @@ gnutls_pkcs11_token_get_url (unsigned int seq, * @output_size: contains the maximum size of the output and will be overwritten with actual * * This function will return information about the PKCS 11 token such - * as the label, id as well as token information where the key is stored. + * as the label, id, etc. * * Returns: %GNUTLS_E_SUCCESS (0) on success or a negative error code * on error. diff --git a/lib/pkcs11_write.c b/lib/pkcs11_write.c index 2e7be6bd6a..e5226a4e09 100644 --- a/lib/pkcs11_write.c +++ b/lib/pkcs11_write.c @@ -610,6 +610,7 @@ cleanup: * @flags: One of GNUTLS_PKCS11_OBJ_* flags * * This function will delete objects matching the given URL. + * Note that not all tokens support the delete operation. * * Returns: On success, the number of objects deleted is returned, otherwise a * negative error value. diff --git a/lib/x509/crq.c b/lib/x509/crq.c index 326ce59ae6..d63cbdde58 100644 --- a/lib/x509/crq.c +++ b/lib/x509/crq.c @@ -771,7 +771,7 @@ gnutls_x509_crq_get_version (gnutls_x509_crq_t crq) * @key: holds a private key * * This function will set the public parameters from the given private - * key to the request. Only RSA keys are currently supported. + * key to the request. * * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a * negative error value.