@node More on certificate authentication @chapter More on certificate authentication @cindex certificate authentication Certificates are not the only structures involved in a public key infrastructure. Several other structures that are used for certificate requests, encrypted private keys, revocation lists, GnuTLS abstract key structures, etc., are discussed in this chapter. @menu * PKCS 10 certificate requests:: * PKIX certificate revocation lists:: * OCSP certificate status checking:: * Managing encrypted keys:: * The certtool application:: * The ocsptool application:: * Smart cards and HSMs:: * Abstract key types:: @end menu @node PKCS 10 certificate requests @section @acronym{PKCS} #10 certificate requests @cindex certificate requests @cindex PKCS #10 A certificate request is a structure, which contain information about an applicant of a certificate service. It usually contains a private key, a distinguished name and secondary data such as a challenge password. @acronym{GnuTLS} supports the requests defined in @acronym{PKCS} #10 @xcite{RFC2986}. Other formats of certificate requests are not currently supported. 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. @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} 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 request is to be signed with a key residing in a PKCS #11 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. @anchor{ex:crq} @verbatiminclude examples/ex-crq.c @node PKIX certificate revocation lists @section 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. 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 time and is required to provide, except for the current issuing time, also the issuing time of the next update. @float Table,tab:crl @multitable @columnfractions .2 .7 @headitem Field @tab Description @item version @tab The field that indicates the version of the CRL structure. @item signature @tab A signature by the issuing authority. @item issuer @tab Holds the issuer's distinguished name. @item thisUpdate @tab The issuing time of the revocation list. @item nextUpdate @tab The issuing time of the revocation list that will update that one. @item revokedCertificates @tab List of revoked certificates serial numbers. @item extensions @tab Optional CRL structure extensions. @end multitable @caption{Certificate revocation list fields.} @end float @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} 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 can be used to sign with a key residing in a PKCS #11 token. @showfuncdesc{gnutls_x509_crl_sign2} @showfuncdesc{gnutls_x509_crl_privkey_sign} Few extensions on the CRL structure are supported, including the CRL number extension and the authority key identifier. @showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id} @node OCSP certificate status checking @section @acronym{OCSP} certificate status checking @cindex certificate status @cindex Online Certificate Status Protocol @cindex OCSP Certificates may be revoked before their expiration time has been reached. There are several reasons for revoking certificates, but a typical situation is when the private key associated with a certificate has been compromised. Traditionally, Certificate Revocation Lists (CRLs) have been used by application to implement revocation checking, however several disadvantages with CRLs have been identified, see for example @xcite{RIVESTCRL}. The Online Certificate Status Protocol (@acronym{OCSP}) is a widely implemented protocol to perform certificate (revocation) status checking. @xcite{RFC2560}. 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. 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. The address can also be provided in the certificate that is being checked. There is an extension field called the Authority Information Access (AIA) which has an access method called @code{id-ad-ocsp} that holds the location of the OCSP responder. There is a function for extracting 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 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 received that the application will need to import into an OCSP response object. The digital signature in the OCSP response needs to be verified against a set of trust anchors before the information in the response can be trusted. The ASN.1 structure of OCSP requests are briefly as follows. It is useful to review the structures to get an understanding of which fields are modified by GnuTLS functions. @example OCSPRequest ::= SEQUENCE @{ tbsRequest TBSRequest, optionalSignature [0] EXPLICIT Signature OPTIONAL @} TBSRequest ::= SEQUENCE @{ version [0] EXPLICIT Version DEFAULT v1, requestorName [1] EXPLICIT GeneralName OPTIONAL, requestList SEQUENCE OF Request, requestExtensions [2] EXPLICIT Extensions OPTIONAL @} Request ::= SEQUENCE @{ reqCert CertID, singleRequestExtensions [0] EXPLICIT Extensions OPTIONAL @} CertID ::= SEQUENCE @{ hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET STRING, -- Hash of Issuer's DN issuerKeyHash OCTET STRING, -- Hash of Issuers public key serialNumber CertificateSerialNumber @} @end example The basic functions to initialize, import, export and deallocate OCSP requests are the following. @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 issuer name hash, issuer key hash, and certificate serial number in binary form. The second is usually 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 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. @showfuncB{gnutls_ocsp_req_get_extension,gnutls_ocsp_req_set_extension} A common OCSP Request extension is the nonce extension (OID 1.3.6.1.5.5.7.48.1.2), which is used to avoid replay attacks of earlier recorded OCSP responses. The nonce extension carries a value that is intended to be sufficiently random and unique so that an attacker will not be able to give a stale response for the same nonce. @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. @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. @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. @showfuncB{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct} @node Managing encrypted keys @section 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. 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 @cindex PKCS #8 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 @code{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. @showfuncB{gnutls_x509_privkey_import_pkcs8,gnutls_x509_privkey_export_pkcs8} @showenumdesc{gnutls_pkcs_encrypt_flags_t,Encryption flags} @subheading @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. In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled using the @code{gnutls_pkcs12_t} type. This is an abstract type that may hold several @code{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. The following functions are available to read a @acronym{PKCS} #12 structure. @showfuncC{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt} @showfuncD{gnutls_pkcs12_bag_get_count,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. @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 @node The certtool application @section The certtool application @cindex certtool This is a program to generate @acronym{X.509} certificates, certificate requests, CRLs and private keys. @example Certtool help Usage: certtool [options] -s, --generate-self-signed Generate a self-signed certificate. -c, --generate-certificate Generate a signed certificate. --generate-proxy Generate a proxy certificate. --generate-crl Generate a CRL. -u, --update-certificate Update a signed certificate. -p, --generate-privkey Generate a private key. -q, --generate-request Generate a PKCS #10 certificate request. -e, --verify-chain Verify a PEM encoded certificate chain. The last certificate in the chain must be a self signed one. --verify Verify a PEM encoded certificate chain. CA certificates must be loaded with --load-ca-certificate. --verify-crl Verify a CRL. --generate-dh-params Generate PKCS #3 encoded Diffie-Hellman parameters. --get-dh-params Get the included PKCS #3 encoded Diffie-Hellman parameters. --load-privkey FILE Private key file to use. --load-pubkey FILE Public key file to use. --load-request FILE Certificate request file to use. --load-certificate FILE Certificate file to use. --load-ca-privkey FILE Certificate authority's private key file to use. --load-ca-certificate FILE Certificate authority's certificate file to use. --password PASSWORD Password to use. -i, --certificate-info Print information on a certificate. --certificate-pubkey Print certificate public key. --pgp-certificate-info Print information on a OpenPGP certificate. --pgp-ring-info Print information on a keyring structure. -l, --crl-info Print information on a CRL. --crq-info Print information on a Certificate Request. --no-crq-extensions Do not use extensions in certificate requests. --p12-info Print information on a PKCS #12 structure. --p7-info Print information on a PKCS #7 structure. --smime-to-p7 Convert S/MIME to PKCS #7 structure. -k, --key-info Print information on a private key. --pgp-key-info Print information on a OpenPGP private key. --pubkey-info Print information on a public key. --fix-key Regenerate the parameters in a private key. --v1 Generate an X.509 version 1 certificate (no extensions). --to-p12 Generate a PKCS #12 structure. --to-p8 Generate a PKCS #8 key structure. -8, --pkcs8 Use PKCS #8 format for private keys. --dsa Use DSA keys. --ecc Use ECC (ECDSA) keys. --hash STR Hash algorithm to use for signing (MD5,SHA1,RMD160,SHA256,SHA384,SHA512). --export-ciphers Use weak encryption algorithms. --inder Use DER format for input certificates and private keys. --inraw Use RAW/DER format for input certificates and private keys. --outder Use DER format for output certificates and private keys. --outraw Use RAW/DER format for output certificates and private keys. --bits BITS specify the number of bits for key generation. --sec-param PARAM specify the security level [low|normal|high|ultra]. --disable-quick-random Use /dev/random for key generationg, thus increasing the quality of randomness used. --outfile FILE Output file. --infile FILE Input file. --template FILE Template file to use for non interactive operation. --pkcs-cipher CIPHER Cipher to use for pkcs operations (3des,3des-pkcs12,aes-128,aes-192,aes-25 6,rc2-40,arcfour). -d, --debug LEVEL specify the debug level. Default is 1. -h, --help shows this help text -v, --version shows the program's version @end example The program can be used interactively or non interactively by specifying the @code{--template} command line option. See below for an example of a template file. @subheading Diffie-Hellman parameter generation To generate parameters for Diffie-Hellman key exchange, use the command: @example $ certtool --generate-dh-params --outfile dh.pem --sec-param normal @end example @subheading Self-signed certificate generation To create a self signed certificate, use the command: @example $ certtool --generate-privkey --outfile ca-key.pem $ certtool --generate-self-signed --load-privkey ca-key.pem \ --outfile ca-cert.pem @end example Note that a self-signed certificate usually belongs to a certificate authority, that signs other certificates. @subheading Private key generation To create a private key (RSA by default), run: @example $ certtool --generate-privkey --outfile key.pem @end example To create a DSA or elliptic curves (ECDSA) private key use the above command combined with @code{--dsa} or @code{--ecc} options. @subheading Certificate generation To generate a certificate using the private key, use the command: @example $ certtool --generate-certificate --load-privkey key.pem \ --outfile cert.pem --load-ca-certificate ca-cert.pem \ --load-ca-privkey ca-key.pem @end example Alternatively you may create a certificate request, which is needed when the certificate will be signed by a third party authority. @example $ certtool --generate-request --load-privkey key.pem \ --outfile request.pem @end example If the private key is stored in a smart card you can generate a request by specifying the private key object URL (see @ref{The p11tool application} on how to obtain the URL). @example $ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \ --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem @end example To generate a certificate using the previous request, use the command: @example $ certtool --generate-certificate --load-request request.pem \ --outfile cert.pem \ --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem @end example @subheading Certificate information To view the certificate information, use: @example $ certtool --certificate-info --infile cert.pem @end example @subheading @acronym{PKCS} #12 structure generation To generate a @acronym{PKCS} #12 structure using the previous key and certificate, use the command: @example $ certtool --load-certificate cert.pem --load-privkey key.pem \ --to-p12 --outder --outfile key.p12 @end example Some tools (reportedly web browsers) have problems with that file because it does not contain the CA certificate for the certificate. To work around that problem in the tool, you can use the --load-ca-certificate parameter as follows: @example $ certtool --load-ca-certificate ca.pem \ --load-certificate cert.pem --load-privkey key.pem \ --to-p12 --outder --outfile key.p12 @end example @subheading Proxy certificate generation Proxy certificate can be used to delegate your credential to a temporary, typically short-lived, certificate. To create one from the previously created certificate, first create a temporary key and then generate a proxy certificate for it, using the commands: @example $ certtool --generate-privkey > proxy-key.pem $ certtool --generate-proxy --load-ca-privkey key.pem \ --load-privkey proxy-key.pem --load-certificate cert.pem \ --outfile proxy-cert.pem @end example @subheading Certificate revocation list generation To create an empty Certificate Revocation List (CRL) do: @example $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ --load-ca-certificate x509-ca.pem @end example To create a CRL that contains some revoked certificates, place the certificates in a file and use @code{--load-certificate} as follows: @example $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem @end example To verify a Certificate Revocation List (CRL) do: @example $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem @end example @subheading Certtool's template file format: A template file can be used to avoid the interactive questions of certtool. Initially create a file named 'cert.cfg' that contains the information about the certificate. The template can be used as below: @example $ certtool --generate-certificate cert.pem --load-privkey key.pem \ --template cert.cfg \ --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem @end example An example certtool template file: @example # X.509 Certificate options # # DN options # The organization of the subject. organization = "Koko inc." # The organizational unit of the subject. unit = "sleeping dept." # The locality of the subject. # locality = # The state of the certificate owner. state = "Attiki" # The country of the subject. Two letter code. country = GR # The common name of the certificate owner. cn = "Cindy Lauper" # A user id of the certificate owner. #uid = "clauper" # If the supported DN OIDs are not adequate you can set # any OID here. # For example set the X.520 Title and the X.520 Pseudonym # by using OID and string pairs. #dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" # This is deprecated and should not be used in new # certificates. # pkcs9_email = "none@@none.org" # The serial number of the certificate serial = 007 # In how many days, counting from today, this certificate will expire. expiration_days = 700 # X.509 v3 extensions # A dnsname in case of a WWW server. #dns_name = "www.none.org" #dns_name = "www.morethanone.org" # An IP address in case of a server. #ip_address = "192.168.1.1" # An email in case of a person email = "none@@none.org" # An URL that has CRLs (certificate revocation lists) # available. Needed in CA certificates. #crl_dist_points = "http://www.getcrl.crl/getcrl/" # Whether this is a CA certificate or not #ca # Whether this certificate will be used for a TLS client #tls_www_client # Whether this certificate will be used for a TLS server #tls_www_server # Whether this certificate will be used to sign data (needed # in TLS DHE ciphersuites). signing_key # Whether this certificate will be used to encrypt data (needed # in TLS RSA ciphersuites). Note that it is preferred to use different # keys for encryption and signing. #encryption_key # Whether this key will be used to sign other certificates. #cert_signing_key # Whether this key will be used to sign CRLs. #crl_signing_key # Whether this key will be used to sign code. #code_signing_key # Whether this key will be used to sign OCSP data. #ocsp_signing_key # Whether this key will be used for time stamping. #time_stamping_key # Whether this key will be used for IPsec IKE operations. #ipsec_ike_key @end example @node The ocsptool application @section The ocsptool application @cindex ocsptool This is a program that can parse and print information about @acronym{OCSP} requests/responses, generate requests and verify responses. @example Ocsptool help Usage : ocsptool [options] -e, --verify-response Verify response. -i, --request-info Print information on a OCSP request. -j, --response-info Print information on a OCSP response. -q, --generate-request Generate a OCSP request. --no-nonce don't add nonce to OCSP request. --load-issuer FILE read issuer certificate from FILE. --load-cert FILE read certificate to check from FILE. --load-trust FILE read trust anchors from FILE. --inder Use DER format for input certificates. -Q, --load-request FILE read DER encoded OCSP request from FILE. -S, --load-response FILE read DER encoded OCSP response from FILE. --outfile FILE Output file. --infile FILE Input file. -V, --verbose More verbose output. -d, --debug integer Enable debugging -v, --version prints the program's version number -h, --help shows this help text @end example @subheading Print information about an OCSP request To parse an OCSP request and print information about the content, the @code{-i} or @code{--request-info} parameter may be used as follows. The @code{-Q} parameter specify the name of the file containing the OCSP request, and it should contain the OCSP request in binary DER format. @smallexample $ ocsptool -i -Q ocsp-request.der @end smallexample The input file may also be sent to standard input like this: @smallexample $ cat ocsp-request.der | ocsptool --request-info @end smallexample @subheading Print information about an OCSP response Similar to parsing OCSP requests, OCSP responses can be parsed using the @code{-j} or @code{--response-info} as follows. @smallexample $ ocsptool -j -Q ocsp-response.der $ cat ocsp-response.der | ocsptool --response-info @end smallexample @subheading Generate an OCSP request The @code{-q} or @code{--generate-request} parameters are used to generate an OCSP request. By default the OCSP request is written to standard output in binary DER format, but can be stored in a file using @code{--outfile}. To generate an OCSP request the issuer of the certificate to check needs to be specified with @code{--load-issuer} and the certificate to check with @code{--load-cert}. By default PEM format is used for these files, although @code{--inder} can be used to specify that the input files are in DER format. @smallexample $ ocsptool -q --load-issuer issuer.pem --load-cert client.pem --outfile ocsp-request.der @end smallexample When generating OCSP requests, the tool will add an OCSP extension containing a nonce. This behaviour can be disabled by specifying @code{--no-nonce}. @subheading Verify signature in OCSP response To verify the signature in an OCSP response the @code{-e} or @code{--verify-response} parameter is used. The tool will read an OCSP response in DER format from standard input, or from the file specified by @code{--load-response}. The OCSP response is verified against a set of trust anchors, which are specified using @code{--load-trust}. The trust anchors are concatenated certificates in PEM format. The certificate that signed the OCSP response needs to be in the set of trust anchors, or the issuer of the signer certificate needs to be in the set of trust anchors and the OCSP Extended Key Usage bit has to be asserted in the signer certificate. @smallexample $ ocsptool -e --load-trust issuer.pem --load-response ocsp-response.der @end smallexample The tool will print status of verification. @subheading Verify signature in OCSP response against given certificate It is possible to override the normal trust logic if you know that a certain certificate is supposed to have signed the OCSP response, and you want to use it to check the signature. This is achieved using @code{--load-signer} instead of @code{--load-trust}. This will load one certificate and it will be used to verify the signature in the OCSP response. It will not check the Extended Key Usage bit. @smallexample $ ocsptool -e --load-signer ocsp-signer.pem --load-response ocsp-response.der @end smallexample This approach is normally only relevant in two situations. The first is when the OCSP response does not contain a copy of the signer certificate, so the @code{--load-trust} code would fail. The second is if you want to avoid the indirect mode where the OCSP response signer certificate is signed by a trust anchor. @subheading Real-world example Here is an example of how to generate an OCSP request for a certificate and to verify the response. For illustration we'll use the @code{blog.josefsson.org} host, which (as of writing) uses a certificate from CACert. First we'll use @code{gnutls-cli} to get a copy of the server certificate chain. The server is not required to send this information, but this particular one is configured to do so. @smallexample $ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem @end smallexample Use a text editor on @code{chain.pem} to create three files for each separate certificates, called @code{cert.pem} for the first certificate for the domain itself, secondly @code{issuer.pem} for the intermediate certificate and @code{root.pem} for the final root certificate. The domain certificate normally contains a pointer to where the OCSP responder is located, in the Authority Information Access Information extension. For example, from @code{certtool -i < cert.pem} there is this information: @smallexample Authority Information Access Information (not critical): Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp) Access Location URI: http://ocsp.CAcert.org/ @end smallexample This means the CA support OCSP queries over HTTP. We are now ready to create a OCSP request for the certificate. @smallexample $ ocsptool --generate-request --load-issuer issuer.pem --load-cert cert.pem --outfile ocsp-request.der @end smallexample The request is sent base64 encoded via HTTP to the address indicated by the id-ad-ocsp extension, as follows. @smallexample $ wget -O ocsp-response.der http://ocsp.CAcert.org/$(base64 -w0 ocsp-request.der) @end smallexample The OCSP response is now in the file @code{ocsp-response.der} and you can view it using @code{ocsptool -j < ocsp-response.der}. To verify the signature you need to load the issuer as the trust anchor. @smallexample $ ocsptool --verify-response --load-trust issuer.pem --load-response ocsp-response.der Verifying OCSP Response: Success. $ @end smallexample This particular OCSP responder includes its signer certificate in the OCSP respnose, so you may extract it and use it together with @code{--load-signer} for verifying the signature directly against the certificate. @smallexample $ ocsptool -j < ocsp-response.der > signer.pem $ ocsptool --verify-response --load-signer signer.pem --load-response ocsp-response.der Verifying OCSP Response: Success. $ @end smallexample You may experiment passing different certificates to @code{--load-trust} and @code{--load-signer} to find common error conditions for OCSP response verification failures. @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 allows decoupling cryptographic keys from the applications that use them providing an additional security layer. Since this can also be achieved in software components such as in Gnome keyring, we will use the term security module to describe such an isolation interface. @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:: * The p11tool application:: @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. @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. @showfuncC{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file,gnutls_certificate_set_x509_simple_pkcs12_file} @node The p11tool application @subsection The p11tool application @anchor{p11tool} @cindex p11tool p11tool is a program that is used to access tokens and security modules that support the PKCS #11 API. It requires individual PKCS #11 modules to be loaded either with the @code{--provider} option, or by setting up the GnuTLS configuration file for PKCS #11 as in @ref{Smart cards and HSMs}. @example p11tool help Usage: p11tool [options] Usage: p11tool --list-tokens Usage: p11tool --list-all Usage: p11tool --export 'pkcs11:...' --export URL Export an object specified by a pkcs11 URL --list-tokens List all available tokens --list-mechanisms URL List all available mechanisms in token. --list-all List all objects specified by a PKCS#11 URL --list-all-certs List all certificates specified by a PKCS#11 URL --list-certs List certificates that have a private key specified by a PKCS#11 URL --list-privkeys List private keys specified by a PKCS#11 URL --list-trusted List certificates marked as trusted, specified by a PKCS#11 URL --initialize URL Initializes a PKCS11 token. --write URL Writes loaded certificates, private or secret keys to a PKCS11 token. --delete URL Deletes objects matching the URL. --label label Sets a label for the write operation. --trusted Marks the certificate to be written as trusted. --private Marks the object to be written as private (requires PIN). --no-private Marks the object to be written as not private. --login Force login to token --detailed-url Export detailed URLs. --no-detailed-url Export less detailed URLs. --secret-key HEX_KEY Provide a hex encoded secret key. --load-privkey FILE Private key file to use. --load-pubkey FILE Private key file to use. --load-certificate FILE Certificate file to use. -8, --pkcs8 Use PKCS #8 format for private keys. --inder Use DER format for input certificates and private keys. --inraw Use RAW/DER format for input certificates and private keys. --provider Library Specify the pkcs11 provider library --outfile FILE Output file. -d, --debug LEVEL specify the debug level. Default is 1. -h, --help shows this help text @end example After being provided the available PKCS #11 modules, it can list all tokens available in your system, the objects on the tokens, and perform operations on them. Some examples on how to use p11tool are illustrated in the following paragraphs. @subsubheading List all tokens @example $ p11tool --list-tokens @end example @subsubheading List all objects The following command will list all objects in a token. The @code{--login} is required to show objects marked as private. @example $ p11tool --login --list-all @end example @subsubheading Exporting an object To retrieve an object stored in the card use the following command. Note however that objects marked as sensitive (typically PKCS #11 private keys) are not allowed to be extracted from the token. @example $ p11tool --login --export [OBJECT URL] @end example @subsubheading Copy an object to a token To copy an object, such as a certificate or private key to a token use the following command. @example $ p11tool --login --write [TOKEN URL] \ --load-certificate cert.pem --label "my_cert" @end example @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 #inlude 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} @showfuncD{gnutls_pubkey_import_openpgp,gnutls_pubkey_import_pkcs11,gnutls_pubkey_import_pkcs11_url,gnutls_pubkey_import_privkey} 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_hash} @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}