doc/man3/X509_sign.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_sign, X509_sign_ctx, X509_verify_ex, X509_verify, X509_REQ_sign,
   6 X509_REQ_sign_ctx, X509_REQ_verify_ex, X509_REQ_verify, X509_CRL_sign,
   7 X509_CRL_sign_ctx, X509_CRL_verify
   8 - sign or verify certificate, certificate request or CRL signature
   9
  10 =head1 SYNOPSIS
  11
  12  #include <openssl/x509.h>
  13
  14  int X509_sign(X509 *x, EVP_PKEY *pkey, const EVP_MD *md);
  15  int X509_sign_ctx(X509 *x, EVP_MD_CTX *ctx);
  16  int X509_verify_ex(X509 *x, EVP_PKEY *pkey, OPENSSL_CTX *libctx, const char *propq);
  17  int X509_verify(X509 *x, EVP_PKEY *pkey;
  18
  19  int X509_REQ_sign(X509_REQ *x, EVP_PKEY *pkey, const EVP_MD *md);
  20  int X509_REQ_sign_ctx(X509_REQ *x, EVP_MD_CTX *ctx);
  21  int X509_REQ_verify_ex(X509_REQ *a, EVP_PKEY *pkey, OPENSSL_CTX *libctx,
  22                         const char *propq);
  23  int X509_REQ_verify(X509_REQ *a, EVP_PKEY *pkey);
  24
  25  int X509_CRL_sign(X509_CRL *x, EVP_PKEY *pkey, const EVP_MD *md);
  26  int X509_CRL_sign_ctx(X509_CRL *x, EVP_MD_CTX *ctx);
  27  int X509_CRL_verify(X509_CRL *a, EVP_PKEY *pkey);
  28
  29 =head1 DESCRIPTION
  30
  31 X509_sign() signs certificate I<x> using private key I<pkey> and message
  32 digest I<md> and sets the signature in I<x>. X509_sign_ctx() also signs
  33 certificate I<x> but uses the parameters contained in digest context I<ctx>.
  34
  35 X509_verify_ex() verifies the signature of certificate I<x> using public key
  36 I<pkey>. Any cryptographic algorithms required for the verification are fetched
  37 using the library context I<libctx> and the property query string I<propq>. Only
  38 the signature is checked: no other checks (such as certificate chain validity)
  39 are performed.
  40
  41 X509_verify() is the same as X509_verify_ex() except that the default library
  42 context and property query string are used.
  43
  44 X509_REQ_sign(), X509_REQ_sign_ctx(), X509_REQ_verify_ex(), X509_REQ_verify(),
  45 X509_CRL_sign(), X509_CRL_sign_ctx() and X509_CRL_verify() sign and verify
  46 certificate requests and CRLs respectively.
  47
  48 =head1 NOTES
  49
  50 X509_sign_ctx() is used where the default parameters for the corresponding
  51 public key and digest are not suitable. It can be used to sign keys using
  52 RSA-PSS for example.
  53
  54 For efficiency reasons and to work around ASN.1 encoding issues the encoding
  55 of the signed portion of a certificate, certificate request and CRL is cached
  56 internally. If the signed portion of the structure is modified the encoding
  57 is not always updated meaning a stale version is sometimes used. This is not
  58 normally a problem because modifying the signed portion will invalidate the
  59 signature and signing will always update the encoding.
  60
  61 =head1 RETURN VALUES
  62
  63 X509_sign(), X509_sign_ctx(), X509_REQ_sign(), X509_REQ_sign_ctx(),
  64 X509_CRL_sign() and X509_CRL_sign_ctx() return the size of the signature
  65 in bytes for success and zero for failure.
  66
  67 X509_verify_ex(), X509_verify(), X509_REQ_verify_ex(), X509_REQ_verify() and
  68 X509_CRL_verify() return 1 if the signature is valid and 0 if the signature
  69 check fails. If the signature could not be checked at all because it was invalid
  70 or some other error occurred then -1 is returned.
  71
  72 =head1 SEE ALSO
  73
  74 L<d2i_X509(3)>,
  75 L<ERR_get_error(3)>,
  76 L<X509_CRL_get0_by_serial(3)>,
  77 L<X509_get0_signature(3)>,
  78 L<X509_get_ext_d2i(3)>,
  79 L<X509_get_extension_flags(3)>,
  80 L<X509_get_pubkey(3)>,
  81 L<X509_get_subject_name(3)>,
  82 L<X509_get_version(3)>,
  83 L<X509_NAME_add_entry_by_txt(3)>,
  84 L<X509_NAME_ENTRY_get_object(3)>,
  85 L<X509_NAME_get_index_by_NID(3)>,
  86 L<X509_NAME_print_ex(3)>,
  87 L<X509_new(3)>,
  88 L<X509V3_get_d2i(3)>,
  89 L<X509_verify_cert(3)>,
  90 L<OPENSSL_CTX(3)>
  91
  92 =head1 HISTORY
  93
  94 The X509_sign(), X509_REQ_sign() and X509_CRL_sign() functions are
  95 available in all versions of OpenSSL.
  96
  97 The X509_sign_ctx(), X509_REQ_sign_ctx()
  98 and X509_CRL_sign_ctx() functions were added OpenSSL 1.0.1.
  99
 100 X509_verify_ex() and X509_REQ_verify_ex() were added in OpenSSL 3.0.
 101
 102 =head1 COPYRIGHT
 103
 104 Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
 105
 106 Licensed under the Apache License 2.0 (the "License").  You may not use
 107 this file except in compliance with the License.  You can obtain a copy
 108 in the file LICENSE in the source distribution or at
 109 L<https://www.openssl.org/source/license.html>.
 110
 111 =cut