sys/man/2/rsa

   1 .TH RSA 2
   2 .SH NAME
   3 asn1dump,
   4 asn1toRSApriv,
   5 decodePEM,
   6 rsadecrypt,
   7 rsaencrypt,
   8 rsagen,
   9 rsaprivalloc,
  10 rsaprivfree,
  11 rsaprivtopub,
  12 rsapuballoc,
  13 rsapubfree,
  14 X509toRSApub,
  15 X509gen,
  16 X509verify \- RSA encryption algorithm
  17 .SH SYNOPSIS
  18 .B #include <u.h>
  19 .br
  20 .B #include <libc.h>
  21 .br
  22 .B #include <mp.h>
  23 .br
  24 .B #include <libsec.h>
  25 .PP
  26 .ta +\w'\fLRSApriv* \fP'u
  27 .B
  28 RSApriv*        rsagen(int nlen, int elen, int nrep)
  29 .PP
  30 .B
  31 mpint*  rsaencrypt(RSApub *k, mpint *in, mpint *out)
  32 .PP
  33 .B
  34 mpint*  rsadecrypt(RSApriv *k, mpint *in, mpint *out)
  35 .PP
  36 .B
  37 RSApub* rsapuballoc(void)
  38 .PP
  39 .B
  40 void    rsapubfree(RSApub*)
  41 .PP
  42 .B
  43 RSApriv*        rsaprivalloc(void)
  44 .PP
  45 .B
  46 void    rsaprivfree(RSApriv*)
  47 .PP
  48 .B
  49 RSApub* rsaprivtopub(RSApriv*)
  50 .PP
  51 .B
  52 RSApub* X509toRSApub(uchar *cert, int ncert, char *name, int nname)
  53 .PP
  54 .B
  55 RSApriv*        asn1toRSApriv(uchar *priv, int npriv)
  56 .PP
  57 .B
  58 void            asn1dump(uchar *der, int len)
  59 .PP
  60 .B
  61 uchar*  decodePEM(char *s, char *type, int *len, char **new_s)
  62 .PP
  63 .B
  64 uchar*  X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen);
  65 .PP
  66 .B
  67 uchar*  X509req(RSApriv *priv, char *subj, int *certlen);
  68 .PP
  69 .B
  70 char*   X509verify(uchar *cert, int ncert, RSApub *pk)
  71 .DT
  72 .SH DESCRIPTION
  73 RSA is a public key encryption algorithm.  The owner of a key publishes
  74 the public part of the key:
  75 .IP
  76 .EX
  77 struct RSApub
  78 {
  79         mpint   *n;     /* modulus */
  80         mpint   *ek;    /* exp (encryption key) */
  81 };
  82 .EE
  83 .LP
  84 This part can be used for encrypting data (with
  85 .IR rsaencrypt )
  86 to be sent to the owner.
  87 The owner decrypts (with
  88 .IR rsadecrypt )
  89 using his private key:
  90 .IP
  91 .EX
  92 struct RSApriv
  93 {
  94         RSApub  pub;
  95         mpint   *dk;    /* exp (decryption key) */
  96
  97         /* precomputed crt values */
  98         mpint   *p;
  99         mpint   *q;
 100         mpint   *kp;    /* k mod p-1 */
 101         mpint   *kq;    /* k mod q-1 */
 102         mpint   *c2;    /* for converting residues to number */
 103 };
 104 .EE
 105 .PP
 106 Keys are generated using
 107 .IR rsagen .
 108 .I Rsagen
 109 takes both bit length of the modulus, the bit length of the
 110 public key exponent, and the number of repetitions of the Miller-Rabin
 111 primality test to run.  If the latter is 0, it does the default number
 112 of rounds.
 113 .I Rsagen
 114 returns a newly allocated structure containing both
 115 public and private keys.
 116 .I Rsaprivtopub
 117 returns a newly allocated copy of the public key
 118 corresponding to the private key.
 119 .PP
 120 The routines
 121 .IR rsaalloc ,
 122 .IR rsafree ,
 123 .IR rsapuballoc ,
 124 .IR rsapubfree ,
 125 .IR rsaprivalloc ,
 126 and
 127 .I rsaprivfree
 128 are provided to aid in user provided key I/O.
 129 .PP
 130 Given a binary X.509
 131 .IR cert ,
 132 the routine
 133 .I X509toRSApub
 134 returns the public key and, if
 135 .I name
 136 is not nil, the CN part of the Distinguished Name of the
 137 certificate's Subject.
 138 (This is conventionally a userid or a host DNS name.)
 139 No verification is done of the certificate signature;  the
 140 caller should check the fingerprint,
 141 .IR sha1(cert) ,
 142 against a table or check the certificate by other means.
 143 X.509 certificates are often stored in PEM format; use
 144 .I dec64
 145 to convert to binary before computing the fingerprint or calling
 146 .IR X509toRSApub .
 147 For the special case of
 148 certificates signed by a known trusted key
 149 (in a single step, without certificate chains),
 150 .I X509verify
 151 checks the signature on
 152 .IR cert .
 153 It returns nil if successful, else an error string.
 154 .PP
 155 .I X509gen
 156 creates a self-signed X.509 certificate, given an RSA keypair
 157 .IR priv ,
 158 a issuer/subject string
 159 .IR subj ,
 160 and the starting and ending validity dates,
 161 .IR valid .
 162 Length of the allocated binary certificate is stored in
 163 .IR certlen .
 164 The subject line is conventionally of the form
 165 .IP
 166 .EX
 167 C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric
 168 .EE
 169 .LP
 170 using the quoting conventions of
 171 .I tokenize
 172 in
 173 .IR getfields (2).
 174 .PP
 175 .I Asn1toRSApriv
 176 converts an ASN1 formatted RSA private key into the corresponding
 177 .B RSApriv
 178 structure.
 179 .PP
 180 .I Asn1dump
 181 prints an ASN1 object to standard output.
 182 .PP
 183 .I DecodePEM
 184 takes a zero terminated string,
 185 .IR s ,
 186 and decodes the PEM (privacy-enhanced mail) formatted section for
 187 .I type
 188 within it.
 189 If successful, it returns
 190 .IR malloc ed
 191 storage containing the decoded section,
 192 which the caller must free,
 193 and sets
 194 .BI * len
 195 to its decoded length.
 196 Otherwise
 197 .B nil
 198 is returned and
 199 .BI * len
 200 is undefined.
 201 If not nil,
 202 .I new_s
 203 is set to the first character beyond the
 204 .I type
 205 section.
 206 .SH SOURCE
 207 .B /sys/src/libsec
 208 .SH SEE ALSO
 209 .IR mp (2),
 210 .IR aes (2),
 211 .IR blowfish (2),
 212 .IR des (2),
 213 .IR dsa (2),
 214 .IR elgamal (2),
 215 .IR rc4 (2),
 216 .IR sechash (2),
 217 .IR prime (2),
 218 .IR rand (2),
 219 .IR rsa (8)