2b93a12b654b7dc1db144dcb8b53ae93bdd70c77
[openssl.git] / doc / crypto / rsa.pod
1 =pod
2
3 =head1 NAME
4
5 rsa - RSA public key cryptosystem
6
7 =head1 SYNOPSIS
8
9  #include <openssl/rsa.h>
10  #include <openssl/engine.h>
11
12  RSA * RSA_new(void);
13  void RSA_free(RSA *rsa);
14
15  int RSA_public_encrypt(int flen, unsigned char *from,
16     unsigned char *to, RSA *rsa, int padding);
17  int RSA_private_decrypt(int flen, unsigned char *from,
18     unsigned char *to, RSA *rsa, int padding);
19
20  int RSA_sign(int type, unsigned char *m, unsigned int m_len,
21     unsigned char *sigret, unsigned int *siglen, RSA *rsa);
22  int RSA_verify(int type, unsigned char *m, unsigned int m_len,
23     unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
24
25  int RSA_size(RSA *rsa);
26
27  RSA *RSA_generate_key(int num, unsigned long e,
28     void (*callback)(int,int,void *), void *cb_arg);
29
30  int RSA_check_key(RSA *rsa);
31
32  int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
33  void RSA_blinding_off(RSA *rsa);
34
35  void RSA_set_default_openssl_method(RSA_METHOD *meth);
36  RSA_METHOD *RSA_get_default_openssl_method(void);
37  int RSA_set_method(RSA *rsa, ENGINE *engine);
38  RSA_METHOD *RSA_get_method(RSA *rsa);
39  RSA_METHOD *RSA_PKCS1_SSLeay(void);
40  RSA_METHOD *RSA_null_method(void);
41  int RSA_flags(RSA *rsa);
42  RSA *RSA_new_method(ENGINE *engine);
43
44  int RSA_print(BIO *bp, RSA *x, int offset);
45  int RSA_print_fp(FILE *fp, RSA *x, int offset);
46
47  int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),
48     int (*dup_func)(), void (*free_func)());
49  int RSA_set_ex_data(RSA *r,int idx,char *arg);
50  char *RSA_get_ex_data(RSA *r, int idx);
51
52  int RSA_private_encrypt(int flen, unsigned char *from,
53     unsigned char *to, RSA *rsa,int padding);
54  int RSA_public_decrypt(int flen, unsigned char *from, 
55     unsigned char *to, RSA *rsa,int padding);
56
57  int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
58     unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
59     RSA *rsa);
60  int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
61     unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
62     RSA *rsa);
63
64 =head1 DESCRIPTION
65
66 These functions implement RSA public key encryption and signatures
67 as defined in PKCS #1 v2.0 [RFC 2437].
68
69 The B<RSA> structure consists of several BIGNUM components. It can
70 contain public as well as private RSA keys:
71
72  struct
73         {
74         BIGNUM *n;              // public modulus
75         BIGNUM *e;              // public exponent
76         BIGNUM *d;              // private exponent
77         BIGNUM *p;              // secret prime factor
78         BIGNUM *q;              // secret prime factor
79         BIGNUM *dmp1;           // d mod (p-1)
80         BIGNUM *dmq1;           // d mod (q-1)
81         BIGNUM *iqmp;           // q^-1 mod p
82         // ...
83         };
84  RSA
85
86 In public keys, the private exponent and the related secret values are
87 B<NULL>.
88
89 B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private
90 keys, but the RSA operations are much faster when these values are
91 available.
92
93 =head1 CONFORMING TO
94
95 SSL, PKCS #1 v2.0
96
97 =head1 PATENTS
98
99 RSA was covered by a US patent which expired in September 2000.
100
101 =head1 SEE ALSO
102
103 L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>,
104 L<rand(3)|rand(3)>, L<RSA_new(3)|RSA_new(3)>,
105 L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>,
106 L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>,
107 L<RSA_generate_key(3)|RSA_generate_key(3)>,
108 L<RSA_check_key(3)|RSA_check_key(3)>,
109 L<RSA_blinding_on(3)|RSA_blinding_on(3)>,
110 L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>,
111 L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
112 L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>,
113 L<RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3)>,
114 L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)> 
115
116 =cut