ref: 84c4c81ceecfa8f51949787fc2dbe7b14164a353
dir: /sys/man/2/rsa/
.TH RSA 2 .SH NAME asn1dump, asn1toRSApriv, asn1encodeRSApriv, asn1encodeRSApub, decodePEM, rsadecrypt, rsaencrypt, rsafill, rsagen, rsaprivalloc, rsaprivfree, rsaprivtopub, rsapuballoc, rsapubfree, X509toRSApub, X509rsagen, X509rsareq, X509rsaverify, X509rsaverifydigest \- RSA encryption algorithm .SH SYNOPSIS .B #include <u.h> .br .B #include <libc.h> .br .B #include <mp.h> .br .B #include <libsec.h> .PP .ta +\w'\fLRSApriv* \fP'u .B RSApriv* rsagen(int nlen, int elen, int nrep) .PP .ta +\w'\fLRSApriv* \fP'u .B RSApriv* rsafill(mpint *n, mpint *e, mpint *d, mpint *p, mpint *q) .PP .B mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out) .PP .B mpint* rsadecrypt(RSApriv *k, mpint *in, mpint *out) .PP .B RSApub* rsapuballoc(void) .PP .B void rsapubfree(RSApub*) .PP .B RSApriv* rsaprivalloc(void) .PP .B void rsaprivfree(RSApriv*) .PP .B RSApub* rsaprivtopub(RSApriv*) .PP .B RSApub* X509toRSApub(uchar *cert, int ncert, char *name, int nname) .PP .B RSApriv* asn1toRSApriv(uchar *priv, int npriv) .PP .B int asn1encodeRSApriv(RSApriv *k, uchar *buf, int len) .PP .B int asn1encodeRSApub(RSApub *pk, uchar *buf, int len) .PP .B void asn1dump(uchar *der, int len) .PP .B uchar* decodePEM(char *s, char *type, int *len, char **new_s) .PP .B uchar* X509rsagen(RSApriv *priv, char *subj, ulong valid[2], int *certlen); .PP .B uchar* X509rsareq(RSApriv *priv, char *subj, int *certlen); .PP .B char* X509rsaverify(uchar *cert, int ncert, RSApub *pk) .PP .B char* X509rsaverifydigest(uchar *sig, int siglen, uchar *edigest, int edigestlen, RSApub *pk) .DT .SH DESCRIPTION RSA is a public key encryption algorithm. The owner of a key publishes the public part of the key: .IP .EX struct RSApub { mpint *n; /* modulus */ mpint *ek; /* exp (encryption key) */ }; .EE .LP This part can be used for encrypting data (with .IR rsaencrypt ) to be sent to the owner. The owner decrypts (with .IR rsadecrypt ) using his private key: .IP .EX struct RSApriv { RSApub pub; mpint *dk; /* exp (decryption key) */ /* precomputed crt values */ mpint *p; mpint *q; mpint *kp; /* k mod p-1 */ mpint *kq; /* k mod q-1 */ mpint *c2; /* for converting residues to number */ }; .EE .PP Keys are generated using .IR rsagen . .I Rsagen takes both bit length of the modulus, the bit length of the public key exponent, and the number of repetitions of the Miller-Rabin primality test to run. If the latter is 0, it does the default number of rounds. .I Rsagen returns a newly allocated structure containing both public and private keys. .I Rsafill returns a newly allocated private key by recomputing .IR kp , .IR kq , and .IR c2 . .I Rsaprivtopub returns a newly allocated copy of the public key corresponding to the private key. .PP The routines .IR rsaalloc , .IR rsafree , .IR rsapuballoc , .IR rsapubfree , .IR rsaprivalloc , and .I rsaprivfree are provided to aid in user provided key I/O. .PP Given a binary X.509 .IR cert , the routine .I X509toRSApub returns the public key and, if .I name is not .BR nil , the CN part of the Distinguished Name of the certificate's Subject. (This is conventionally a userid or a host DNS name.) No verification is done of the certificate signature; the caller should check the fingerprint, .IR sha1(cert) , against a table or check the certificate by other means. X.509 certificates are often stored in PEM format; use .I dec64 to convert to binary before computing the fingerprint or calling .IR X509toRSApub . For the special case of certificates signed by a known trusted key (in a single step, without certificate chains), .I X509rsaverify checks the signature on .IR cert . It returns .B nil if successful, else an error string. .PP .I X509rsaverifydigest takes a encoded PKCS #1 signature as used in X.509 as .IR sig [ siglen ] and verifies it against the expected cryptographic hash .IR edigest [ edigestlen ] of the signed data; returning .B nil on success or an error string. .PP .I X509rsagen creates a self-signed X.509 certificate, given an RSA keypair .IR priv , a issuer/subject string .IR subj , and the starting and ending validity dates, .IR valid . Length of the allocated binary certificate is stored in .IR certlen . The subject line is conventionally of the form .IP .EX C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric .EE .LP using the quoting conventions of .I tokenize in .IR getfields (2). .PP .I Asn1toRSApriv converts an ASN1 formatted RSA private key into the corresponding .B RSApriv structure. .PP .I Asn1encodeRSApriv and .I asn1encodeRSApub export a .B RSApriv or .B RSApub structure to ASN1 format. On success, .I buf is filled and the encoded byte length is returned. Otherwise .B -1 is returned and error string is set. .PP .I Asn1dump prints an ASN1 object to standard output. .PP .I DecodePEM takes a zero terminated string, .IR s , and decodes the PEM (privacy-enhanced mail) formatted section for .I type within it. If successful, it returns .IR malloc ed storage containing the decoded section, which the caller must free, and sets .BI * len to its decoded length. Otherwise .B nil is returned and .BI * len is undefined. If not .BR nil , .I new_s is set to the first character beyond the .I type section. .SH SOURCE .B /sys/src/libsec .SH SEE ALSO .IR mp (2), .IR aes (2), .IR blowfish (2), .IR des (2), .IR dsa (2), .IR elgamal (2), .IR rc4 (2), .IR sechash (2), .IR prime (2), .IR rand (2), .IR rsa (8)