doc/man3/X509_sign.pod

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